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About This Book 


The Operating System/2 Version 1.2 (OS/2) Procedures Language 2/REXX Programming Reference is a 
technical reference for professional programmers who develop system programs and applications using 
calls for the Restructured Extended eXecutor (REXX) language. 

This book also provides some guidance information on how to use the calls. It is intended to be used with 
the Operating System/2 Version 1 .2 Programming Guide. 

Prerequisite Knowledge 

This book is intended for application developers who know how to program in REXX. The information 
also assumes you are new to programming with OS/2 and the Presentation Manager. You should under- 
stand the OS/2 services available to users. Further information on these can be obtained from the OS/2 
Product library. 

Conventions used in Call Descriptions 

The documentation of each call contains these sections: 

Call name The call name at the top of each page, followed by a brief description of the call. 

Parameters Each parameter is listed with its data type and a brief description. 

There are three kinds of parameters: 

Input Specified by the programmer. 

Output Returned by OS/2. 

Input/Output Specified by the programmer and modified by OS/2. 

A list of possible return codes or errors (where appropriate) is included in this 
section. Some functions do not have return codes or error messages. 

Remarks Additional information about the function, where required. 

Bindings C and Assembler languages. 

Example An example is shown in C language for some functions. 

Programming Note: The functions in this book are named in mixed-case for readability, but are known to 
the system as uppercase character strings. If you are using a compiler that generates a mixed- 
case external name, you should code the OS/2 function calls in uppercase. 

Sample Programs 

The OS/2 tools package contains sample programs and files that demonstrate common programming 
techniques using REXX. The programs are: 

CALLREXX.CM D Calls REXX from a C program 

RXMACDLL.CMD Uses the external functions interface 

RXSUBDLL.CMD Uses the subcommand interface. 

Another file of interest is RXSTRING.DOC, which explains the RXSTRING.LIB library. 

Related Publications 

Three books that you will find useful along with this book are: 

• The Operating System/2 Version 1.2 Procedures Language 2/REXX User's Guide, available sepa- 
rately. 

• The Operating System/2 Version 1.2 Procedures Language 2/REXX Reference, available separately. 

• The REXX Language: A Practicai Approach to Programming , by M. F. Cowlishaw, published by 
Prentice-Hall, Inc. 
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The Operating System/2 Version 1.2 Programming Overview introduces the programming concepts that 
you should understand before you begin developing applications to run on OS/2, and describes the set of 
books, tools, programming aids, and sample programs that make up the OS/2 Programming Tools and 
Information Library. 

Details of publications for OS/2 Version 1.2 and related products are shown in the Library Diagram on 
page v. 


iv 


OS/2 REXX Programming Reference 



OS/2 Product 


Separate Order 
(no charge) 


Systems Application 
Architecture 


IBM Operating System/2 
Standard Edition 
Version 1.2 

Getting Started 

Using Advanced Features 

Product Information 

6024926 3.5" diskette 
6024930 5.25" diskette 


OS/2 Programming Tools 
and Information 


IBM Operating System/2 
Version 1.2 

Installation 

Programming Overview 
Programming Guide 
Building Programs 
Dialog Tag Language 
Guide and Reference 
Dialog Manager Guide 
and Reference 
Dialog Manager and 
Dialog Tag Language 
Reference Summary 
Programming Reference 
(3 books) 

Bindings Reference for 
Presentation Manager 
(4 books for COBOL/2, 
FORTRAN/2, C/2, and 
Macro Assembler/2) 

I/O Subsystems and 
Device Support 
(2 books) 

Systems Application 
Architecture 
Common User Access: 
Advanced Interface 
Design Guide 

6024929 


Keyboards and Code Pages 
6280345 

Available Separately 

Command Reference 

6024928 

Service Coordinator’s 
Guide 

15F2214 


Programming Languages 


IBM Basic Compiler/2 
Version 1.0 6280179 


IBM Macro Assembler/2 
Version 1.0 6280181 


IBM Pascal Compiler/2 
Version 1.0 6280183 


IBM FORTRAN/2 
Version 1.02 6280185 


IBM COBOL/2 
Version 1.0 6280207 


IBM C/2 

Version 1.1 6280284 


An Overview 


GC26-4341 


Writing Applications: 
A Design Guide 

SC26-4362 


Common User Access: 
Advanced Interface 
Design Guide 
SC26-4582 


Common User Access: 
Basic Interface Design 
Guide 
SC26-4583 


Common Programming 
Interface 


C Reference - Level 2 
SC09-1308 


COBOL Reference 
SC26-4354 


Dialog Reference 
SC26-4356 


FORTRAN Reference 
SC26-4357 


Procedures Language 
Reference 
SC26-4358 


Presentation Reference 
SC26-4359 


Notes: 

1. CodeView ™ is available with IBM C/2 Version 1.1 and upon request. An order form is available with 
the OS/2 Standard Edition Version 1.2 Product. It is also compatible with the Macro Assembler/2, 
Pascal Compiler/2, and BASIC Compiler/2 listed above. 


™ Trademark of Microsoft Corporation 
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2. IBM C/2 Version 1.1 is available on 5.25 in. diskette. An order form is available in the C/2 package. 

3. See your IBM representative for ordering information. 
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Chapter 1. Introduction to the REXX API 

This book describes the Procedures Language/2 REXX Application Programming Interface (API) for OS/2 
and discusses the following topics: 

• Invoking the REXX Interpreter 

• Subcommand processing 

• External functions 

• Macrospace interface 

• Variable pool interface 

• System exits. 

Note: Throughout this book the term application is used to refer to programs written in languages other 
than REXX. Examples of calling conventions are given in the C and Assembler programming lan- 
guages. The functions described are, however, also available to PASCAL. 


Using the REXX APIs 

The features described in this book allow an application to extend many parts of the REXX language. 

This includes providing handlers for subcommand, external function, and system exit processing. These 
handlers are similar in the ways that they must be coded, compiled, and packaged. 

In addition, REXX provides a macrospace interface that allows applications to store and execute REXX 
routines in memory and thereby minimize disk access. Also, REXX provides the means for applications 
to manipulate the variables in REXX programs through the variable pool interface. 


Subcommands 

Subcommands are single clauses consisting of an expression. The expression is evaluated and the 
result is passed as a command string to the currently addressed environment. Subcommands are used 
in the context of REXX running as a macro processor under some environment or program. Refer to 
Chapter 3, “Subcommand Interface” on page 3-1 for more information. 


Functions 

Functions are direct extensions to the capabilities of REXX. An application (including REXX itself) can 
provide a function to augment the function set of REXX. Unlike subcommands, which generally corre- 
spond to the application's normal command set, functions are generally specifically for REXX and may 
only have a meaning from within REXX. They may be as simple as an encapsulation of several base 
REXX instructions or as complex as a large library of functions outside REXX and written in some other 
programming language. Refer to Chapter 4, “External Functions” on page 4-1 for more information. 

System Exits 

System exits allow REXX to operate under programmer-defined variations of the operating system. By 
using these exits, specific REXX actions can be executed as calls to routines provided by the caller of the 
interpreter, instead of using code of the interpreter itself. Refer to Chapter 7, “System Exits” on 
page 7-1 for more information. 

Macrospace Interface 

There are times when REXX is the language best suited for implementing an external function, such as 
when the main purpose of a function is to manipulate strings. Normally, REXX external functions are 
stored on a system’s hard disk. If the function is called repeatedly, the hard-disk search and load time 
can add significant overhead to the total execution time of the calling REXX procedure. 

The macrospace interface lets an application store REXX procedures in memory so they are executed 
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there, thereby avoiding hard-disk overhead. These external functions can be thought of as high-usage 
macros; they can be loaded into a macro space. Refer to Chapter 5, “Macrospace Interface” on 
page 5-1 for more information. 


Variable Pool Interface 

REXX provides an API to allow certain applications, such as subcommands and external functions, to 
read and modify the current set of variables being used by a REXX procedure. Variables can be read, 
modified, and dropped. All variables can be queried. Certain private REXX information, such as the 
version or source strings, can be queried. The applications provide control information to the provided 
interface that instruct REXX what changes to make. REXX will then process the request internally; the 
applications do not need to know the contents of the REXX variable pool to make direct changes. All 
changes are made indirectly through the shared variable request block. Refer to Chapter 6, “Variable 
Pool Interface” on page 6-1 for more information. 


General Characteristics 

Here are some basic requirements for applications to be used as handlers for subcommand, external 
function, and system exit processing: 

• A handler must be written as a large model program. In addition, it must: 

- Use its caller’s stack segment 

- Set up its own data segment 

- Be entered by a far call 

- Obey the PASCAL calling conventions. 

Note: Under the IBM C/2 Compiler Version 1.1 the -Alfu compiler switches force the registers to be 
properly set up. 

• A handler must be packaged , either as: 

- Part of an OS/2 Dynamic Link Library (a dynalink or DLL), or 

- Part of an executable (.EXE) module. 

• A handler must be registered with REXX before it can be used. The registration tells REXX where the 
handler is and how it can be invoked. For example, the information provided on the registration of a 
dynalink external function includes the name of the function, the name of the dynalink library con- 
taining the handler, and the name of the procedure within the dynalink that implements the function. 
Also note: 

- Dynalink handlers are universal to the OS/2 system; they can be invoked from a REXX procedure 
running in any process in any OS/2 session. 

- .EXE handlers are local to the registering process; this means that handlers packaged as part of 
an .EXE module can only be invoked by a REXX procedure running in the same process that reg- 
istered it. 


Data Types and Structures 

Many of the calls described in this book require a method by which arguments may be passed. The data 
structure named RXSTRING is used for communication between the REXX interpreter and application 
programs. The arguments passed may consist of short strings (strings residing entirely within one 
segment) or huge strings (single strings spanning multiple segments). The following structure and 
macros are used to describe an RXSTRING. 
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C Language 

/*** Structure for external interface string (RXSTRING) */ 


#define RXAUTOBUFLEN 256L 


#define RXNULLSTRING(r) 
#define RXZEROLENSTRI NG ( r) 
#define RXVALIDSTRING(r) 
Idefine RXSTRLEN(r) 

#define RXSTRPTR(r) 

#define MAKERXSTR I NG ( r , p , 1 ) 


(1 (r).strptr) 

((r). strptr && ! (r). strl ength) 

((r). strptr && (r) .strlength) 
(RXNULLSTRING(r) ?OL: (r) . strl ength) 

(r). strptr 

(r).strptr=(PCH)p; (r) .strlength=(ULONG)l 


typedef struct { 

ULONG strlength; 

PCH strptr; 

} RXSTRING; 


/* length of string */ 

/* far pointer to string */ 


typedef RXSTRING FAR *PRXSTRING; /* pointer to a RXSTRING */ 


Assembler Language 

;*** Structure for external interface string (RXSTRING) 


RXAUTOBUFLEN 

equ OOOO01Q0h 


RXSTRING struc 

strl ength 

dd ? 

; length of string 

strptr 

RXSTRING ends 

dd ? 

; far pointer to string 


Notes: 

1. REXX arguments either may be given a value (which may be null, 1 ') or not specified. 

• If an argument is specified, the appropriate parts of the RXSTRING will be given values. 

• If a null character ( 1 1 ) is specified as the argument, strlength will be zero, and strptr will be non- 
zero. 

• If no argument is specified, strptr will be zero. 

2. The huge mode of RXSTRING contains the same information as the short mode, except that the 
memory is allocated through a call to DosAllocHuge. Through this convention, strings in a user’s 
program can span multiple segments. 

3. In certain instances (such as subcommand calls, function calls, and some exit calls), the interpreter 
will provide an RXSTRING with a strlength and buffer size of 250 for the return of information. If the 
data for return from these calls is less than 250 characters in length, the program should copy the 
data into this buffer and reset the strlength field accordingly. 
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Chapter 2. Invoking the REXX Interpreter 


The REXX interpreter can be called directly from the operating system or from within an application. 


From OS/2 

The standard OS/2 CMD.EXE shell calls the interpreter for the user: 

• At OS/2 command prompts. 

• In calls from CMD (batch) files. Use the OS/2 CALL command to invoke a REXX program in a batch 
file if you want control to return to the caller. 

• From the Desktop Manager window in Presentation Manager. 

From Within an Application 

REXXSAA is the function that calls the REXX interpreter from an application program. Procedures run in 
the same session, process, and thread as the caller. 

The REXX processor is an OS/2 Dynamic link library (DLL) that is fully re-entrant and allows recursive 
entry by the same thread in a process. The processor supports different procedures running independ- 
ently in multiple threads within the same process. 

A C-language prototype for calling REXX is included in the file REXXSAA.H in the installation package. 
Likewise, an Assembler-language prototype is included in the file REXXSAA.INC. 
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REXXSAA - 
Call Interpreter 


This call allows the user to call the REXX interpreter from an application program. 


REXXSAA (ArgCount, ArgList, ProgramName, Instore, EnvName, CallType, Exits, ReturnCode, Result) 


Parameters 

ArgCount (SHORT) - input 

The number of arguments supplied for this call to the REXX interpreter. 

ArgList (PRXSTRING) - input 

An array of RXSTRING items that describes the arguments for this call to the REXX interpreter. 
ProgramName (PSZ) - input 

A pointer to an ASCIIZ string containing at least the filename and, optionally, the extension and full 
drive and path specification of the REXX procedure. If no file extension is specified, a default of 
".CMD" is supplied. If no path is given, the normal OS/2 file search (current directory then environ- 
ment path) will be performed. For example: C:\UTIL\PLAYTIME.CMD. 

Instore (PRXSTRING) - input 

An array of two descriptors for in-storage REXX procedures: 

!nstore[0] An RXSTRING describing the memory buffer containing the source of the procedure. 

The source must be in the same format as if it were on disk (that is, complete with car- 
riage returns, line feeds, and end-of-file characters [implied at end-of-string]). 
lnstore[1] A second RXSTRING, used initially to return the tokenized image of the source in 

DosAllocSeg or DosAllocHuge space from the interpreter to the cailer. Subsequently, 
the caller can pass this tokenized image back to the interpreter. The interpreter will use 
this tokenized image and thus save the pre-tokenization time. See Remarks below. 

If Instore is specified, no disk search will be performed; ProgramName will be used only as the name 
of the procedure. If no instorage buffer is to be supplied, the Instore pointer should be null. 

EnvName (PSZ) - input 

A pointer to a string specifying the initial interpreter address environment. If no environment name 
is specified, the initial address will default to the file extension. If specified, this value must be in the 
form of an ASCIIZ string. 

CallType (SHORT) - input 

A flag describing how REXX was called; possible values are: 

RXCOMMAND as a command 

RXSUBROUTINE as a subroutine 

RXFUNCTION as a function. 

Exits (PRXSYSEXIT) - input 

An array of RXSYSEXIT elements that contains pointers to subcommand environment names and an 
integer code identifying the exit. The last RXSYSEXIT element must contain the code RXENDLST that 
indicates the end of the system exit list. Set this parameter to null if there are no system exits pro- 
vided. See Chapter 7, “System Exits" on page 7-1 for system exit details. 

ReturnCode (PSHORT) - input 

If the Result string is numeric, it will be converted to an integer and also returned in ReturnCode. 
Result (PRXSTRING) - output 

The RETURN or EXIT value from the ProgramName program. 


2-2 OS/2 REXX Programming Reference 







REXXSAA - 
Call Interpreter 


Returns 

An integer return code from a call to REXXSAA may be issued by the REXX interpreter or from OS/2. The 

possible return codes are: 

negative Interpreter errors. These are the standard SAA-defined Interpreter error codes. Refer 

to Appendix, Errors Returned from REXX Calls for a description of these error condi- 
tions. 

0 No errors occurred. Procedure executed normally. 

positive OS/2 return code indicating problems finding or loading the interpreter. See the return 

codes for the OS/2 functions DosLoadModule and DosGetProcAddr for details. 

Remarks 

With regard to in-storage procedures: 

• Memory allocated by Instore must be released through DosFreeSeg by the caller; once the tokenized 
image is returned to the caller the memory is no longer tracked by REXX. 

• Whenever the source is changed, the tokenized image must be released and lnstore\_1 ] must specify 
an empty RXSTRING. 

• If lnstore[1 ] is specified, /n$fore[0] need not actually contain the source (that is, it may be empty). 

• To prevent in-storage tokenization, set Instoreil ] to an invalid RXSTRING. 

C Language 

short argc, rc; 

char *rexxsaafile, *envnam; 

RXSTRING *argv, instor, retval; 

RXSYSEXIT *sysexit; 

return_code » REXXSAA (argc, argv, rexxsaafile, instor, envnam, RXCOMMAND, sysexit, &rc, &retstr); 

Assembler Language 

@REXXSAA macro ac,av,rf ,ins,env,ct,sex,rc,ret 

^define REXXSAA 

@pushw ac ; Num of args passed to rexx 

@pushs av ; Array of args passed to rexx 

@pushs rf ; [d: ] [path] filename [.ext] 

@pushs ins ; Loc of rexx proc in memory 

0pushs env ; ASCI IZ initial environment. 

@pushw ct ; type (command, subrtn,funct) 

@pushs sex ; SysExit env. names & codes 

@pushs rc ; Ret code from if numeric 

@pushs ret ; Retval ue from the rexx proc, 

call far ptr REXXSAA 
endm 
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Chapter 3. Subcommand Interface 


An application can be dynamically made known to the REXX interpreter by name as an environment 
accessible by the REXX ADDRESS instruction. To do this, the application must be registered as a specific 
subcommand environment. This can be accomplished through the RXSUBCOM interface. 


Writing Subcommand Handlers 

Because subcommands are closely associated with a given application, they are written as part of the 
application. The subcommand code can reside in the same module (.EXE or DLL) as the application, or it 
can reside in an accessory dynalink. Any separate procedure that can be registered with REXX and 
follows the appropriate conventions can be a handler. 

For details on the requirements and options for packaging API handlers, see " General Characteristics” 
on page 1-2. The library name must be the same as the file name of the dynalink or .EXE files being 
used. 

Documentation of subcommand handlers packaged as dynalink libraries must specify the library name 
(used by DosLoadModule) of the dynalink created; see note 1 on page 3-2. This library name must be 
used in order to register the subcommand and may be needed in order to resolve duplicate environment 
names. The procedure name of the subcommand handler must also be published. This procedure name 
must be exported from the dynalink library. 


Invocation 


Here is a sample subcommand handler definition and invocation:. 


SHORT API ENTRY my_subcom 
RXSTRING, 
PUSHORT, 
PRXSTRING 
); 


( 

/* Command string passed from the caller 
/* pointer to short for return of flags 
/* pointer to RXSTRING for return string 


V 

*/ 

*/ 


unsigned short pascal far my_subcom (command, flags, retstr) 
RXSTRING command; 
unsigned short far *flags; 

RXSTRING far *retstr; 


Where: 

command is the entire command string as resolved by REXX. 

flags are flags returned by the subcommand handler to the interpreter to indicate successful com- 

pletion, error, or failure conditions. 

RXSUBCOM_OK Subcommand completed normally 

RXSUBCOM_ERROR Error in subcommand 

RXSUBCOM_FAILURE Failure in subcommand 

retstr the address of a RXSTRING to define your result in. See “Returning Result Values” on 
page 4-2 for additional information. 


These arguments correspond to the same arguments defined for the function RxSubcomExecute, 
described on page 3-5. 

• The subcommand handler is passed the command as a RXSTRING, the pointer to the flag storage 
area and the pointer to a RXSTRING for the subcommand result string. 

• The subcommand returns an integer return code that is placed in the REXX special variable RC or 
returned to the caller of RxSubcomExecute in the last (RC) argument. 

- if a non-zero number is returned, that number is used as the return code. 
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If zero is returned and the result RXSTRING is not empty, the return code is set to the value of 
the result RXSTRING. 

Otherwise the return code is set to zero. 


Duplicate Environment Names 

Multiple subcommand handlers can register themselves for any given subcommand environment name. 
However, for any given OS/2 “boot” there are unique library names associated with individual handlers 
packaged in DLLs (see 1). These library names should be documented and published with the 
instructions for the subcommand handlers. To make subcommand environment names unique the user 
can incorporate this documented library name into the subcommand environment addressed. 

For example, assume that the fictitious QED Corporation produces an editor whose subcommand envi- 
ronment is EDIT, packages it in QEDIT.DLL, and gives it a library name of QEDIT. At the same time, the 
fictitious XYZ Corporation produces a word processor whose subcommand environment is also EDIT, but 
packages it as XWORD.DLL with a library name of XWORD. 

The subcommand handler to be used can be identified by providing the library name when addressing 
the subcommand environment. For example, the REXX subcommand ADDRESS • Edi t.Qedit ' will send 
subcommands to the EDIT environment established by the QEDIT dynalink. Likewise, the subcommand 
ADDRESS 'Edit.Xword' will send subcommands to the EDIT environment established by the XWORD 
dynalink. 

Notes: 

1. The library names mentioned here are the ModuleNames used on DosLoadModule calls. These 
names are found along the OS/2 LIBPATH path so there can be only one handler of library name 
found until LIBPATH is changed and the system re-booted or libraries are unloaded and moved 
around in the subdirectories searched through LIBPATH. 

2. Providing library qualifying information is only necessary for duplicate dynalink subcommand envi- 
ronments because of the established subcommand environment search order. 

Search Order 

Because multiple subcommand handlers can register by the same environment name, it is necessary to 
establish a subcommand handler search order. 

When a dynalink library name is specified with the ADDRESS instruction, REXX invokes the handler reg- 
istered for that environment and packaged in that library. If the specified handler is not available, an 
error is returned. 

If no dynalink library name is specified: 

• The registered handler chain is searched for a matching environment name that was registered from 
the current process ID and session ID (essentially an .EXE subcommand handler entry point). 

• If there is no local handler, search the chain for the first matching handler that can be found and 
used. 

• If none is found, return an error. 


Subcommand Interface Calls 

The calls that you use for registering and manipulating subcommand interfaces are: 

• RxSubcomDrop (Deregister Subcommand Environment) 

• RxSubcomExecute (Send Commands to Subcommand Environment) 

• RxSubcomLoad (Load Subcommand Environment) 

• RxSubcomQuery (Query Subcommand Environment Name) 

• RxSubcomRegister (Register Subcommand Environment). 
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Sample Subcommand Calls 

char far *name, far *d!lname; 

unsigned short exist, flags, rc, return_code; 

double userword; 

SCBLOCK scb; 

RXSTRING command, retstr; 


return_code * RxSubcomRegister (&scb); 

return_code = RxSubcomDrop (name, dll name); 

return_code = RxSubcomLoad (name, dll name); 

return_code s RxSubcomQuery (name, dll name, ftexist, &userword); 

return_code = RxSubcomExecute (name, dll name, command, &flags, &rc, &retstr); 

The calls are described on the remaining pages of this chapter. 


Chapter 3. Subcommand Interface 3-3 



RxSubcomDrop - 

Deregister Subcommand Environment 


This call allows the user to deregister a subcommand environment 


RxSubcomDrop (EnvName, ModuleName) 


Parameters 

EnvName (PSZ) - input 

A pointer to a null terminated (ASCIIZ) subcommand environment name string. 

ModuleName (PSZ) - input 

A pointer to a null terminated (ASCIIZ) string containing the library name of the dynalink library con- 
taining the registered subcommand handler. This name may be a NULL if there are no duplicate 
subcommand environment names registered. If there are multiple subcommand handlers for a given 
environment name and a library name is not provided, the search order documented in “Search 
Order” on page 3-2 is used for environment resolution. Also see “Duplicate Environment Names” 
on page 3-2. 


Returns 

0 RXSUBCOMJDK 

30 RXSUBCOMjsJOTREG 

40 RXSUBCOM_NOCANDROP 

1003 RXSUBCOM_BADTYPE 


Remarks 

The environment is dropped or deregistered from the active subcommand environment list. 

C Language 

/*** RxSubcomDrop - Drop a Subcommand environment */ 

USHORT API ENTRY RxSubcomOrop( 

PSZ, /* Name of the Environment */ 

PSZ); /* DLL Module Name */ 


Assembler Language 


* RxSubcomDrop - Drop a Subcommand environment 


* ^RxSubcomDrop *Environment, *Dllname 


^RxSubcomDrop 


macro 

env,dll 


Qdefine 

RXSUBCOMDROP 


@pushs 

env ; 

Name of the Environment 

@pushs 

dll ; 

DLL Module Name 

call 

far ptr RXSUBCOMDROP 

endm 
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RxSubcomExecute - 

Send Commands to Subcommand Environment 


This call allows the user to send commands to a subcommand environment. 


RxSubcomExecute (EnvName, ModuleName, Command, Flags, RetVal, Result) 


Parameters 

EnvName (PSZ) - input 

A pointer to a null terminated (ASCIIZ) subcommand environment name string. 

ModuleName (PSZ) - input 

A pointer to a null terminated (ASCIIZ) string containing the library name of the dynalink library con- 
taining the registered subcommand handler. This name may be a NULL if there are no duplicate 
subcommand environment names registered. If there are multiple subcommand handlers for a given 
environment name and a library name is not provided, the search order documented in “Search 
Order" on page 3-2 is used for environment resolution. Also see “Duplicate Environment Names" 
on page 3-2. 

Command (RXSTRING) - input 

A string describing the entire command string. 

Flags (PUSHORT) - output 

A pointer to an integer of flags, which is used to notify the caller of failure to locate a subcommand or 
of errors encountered while executing the subcommand. This information is reflected by the inter- 
preter during TRACE (errors) activity. See RxSubcom Flag Definitions on page 3-1 for definitions of 
the flags. 

RetVal (PUSHORT) - output 

A pointer to the return code from the subcommand handler. 

Result (PRXSTRING) - output 

A pointer to the result of the subcommand processing. The subcommand handler modifies the Result 
structure for the returned string. 

Note: The string returned from the subcommand handler is allocated segments which are given to 
the caller. The caller uses DosFreeSeg to free the returned string when finished with it. See 
“Returning Result Values” on page 4-2. 

Returns 

0 RXSUBCOM_OK 

30 RXSU BCOM_NOTREG 

50 RXSUBCOM_LOADERR 

1 27 RXSUBCOM_NOPROC 

Remarks 

The REXX interpreter invokes the appropriate subcommand handler for the specified subcommand envi- 
ronment name and library (if needed). 
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RxSubcomExecute - 

Send Commands to Subcommand Environment 


C Language 

/*** RxSubcomExecute - Execute a command in an environment */ 


USHORT API ENTRY RxSubcomExecute ( 
PSZ, 

PSZ, 

PRXSTRING, 

PUSHORT, 

PUSHORT, 

PRXSTRING ); 


/* Name of Subcommand Environ */ 
/* Module name of its' DLL */ 
/* Command string to be passed*/ 
/* Stor for error flag notice */ 
/* Stor for rc from handler */ 
/* Stor for returned string */ 


lendif /* INCL_RXSUBCOM */ 


Assembler Language 


* RxSubcomExecute - Execute a command in an environment 

i* GRxSubcomExecute *Environment, *Dllname, *Cmdstring, *flag, 
*rc, *return 


©RxSubcomExecute macro 
©define 
©pushs 
©pushs dll 
©pushs cmd 
©pushs flag 
©pushs rc 
©pushs ret 
call far ptr 
endm 


; Name of Subcommand Environ 
; Module name of its' DLL 
; Command string to be passed 
; Stor for error flag notice 
; Stor for rc from handler 
; Stor for returned string 
RXSUBCOMEXECUTE 


env.dll , cmd, flag, rc, ret 
RXSUBCOMEXECUTE 
env 
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RxSubcomLoad - 
Load Subcommand Environment 


This call allows the user to load a subcommand environment packaged in a dynalink. 


RxSubcomLoad (EnvName, ModuleName) 

Parameters 

EnvName ( PSZ ) - input 

A pointer to a null terminated (ASCIIZ) subcommand environment name string. 

ModuleName (PSZ) - input 

A pointer to a null terminated (ASCIIZ) string containing the library name of the dynalink library con- 
taining the registered subcommand handler. This name may be a NULL if there are no duplicate 
subcommand environment names registered. If there are multiple subcommand handlers for a given 
environment name and a library name is not provided, the search order documented in "Search 
Order" on page 3-2 is used for environment resolution. Also see "Duplicate Environment Names” 
on page 3-2. 

Returns 

0 RXSUBCOM.OK 

30 RXSUBCOM_NOTREG 

50 RXSUBCOM_LOADERR 

1 27 RXSUBCOMJMOPROC 

Remarks 

If a subcommand environment is registered by library and routine name, a caller may wish to have the 
REXX interpreter issue an explicit load for the environment-handling routines. 

C Language 

/*** RxSubcomLoad - Load a Subcommand environment */ 

USHORT API ENTRY RxSubcomLoad ( 

PSZ, /* Name of the Environment */ 

PSZ); /* DLL Module Name */ 


Assembler Language 

;* RxSubcomLoad - Load a Subcommand environment 
» 

;* ^RxSubcomLoad *Environment, *Dllname 
» 

GRxSubccmLoad macro env.dll 

^define RXSUBCOMLOAD 

@pu$h$ env ; Name of the Environment 

Opushs dll ; DLL Module Name 

call far ptr RXSUBCOMLOAD 
endm 
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RxSubcomQuery - 

Query Subcommand Environment Name 


This call allows the user to query a subcommand environment name. 


RxSubcomQuery (EnvName, ModuleName, Flag, UserWord) 


Parameters 

EnvName (PSZ) - input 

A pointer to a null-terminated (ASCIIZ) subcommand environment name string. 

ModuleName (PSZ) - input 

A pointer to a null-terminated (ASCIIZ) string containing the library name of the dynalink library con- 
taining the registered subcommand handler. This name may be a NULL if there are no duplicate 
subcommand environment names registered. If there are multiple subcommand handlers for a given 
environment name and a library name is not provided, the search order documented in “Search 
Order" on page 3-2 is used for environment resolution. Also see “Duplicate Environment Names" 
on page 3-2. 

Flag (PUSHORT) - output 

A pointer to an indicator of whether the subcommand identified by EnvName is registered or not. If 
Flag is set to 0, the subcommand is not registered. If Flag is set to 1, the subcommand is registered. 

UserWord (double far *) - output 

The double word of data saved as scbuser during the registration process. 

Returns 

0 RXSUBCOM_OK 

30 RXSUBCOM_NOTREG 

1003 RXSUBCOM_BADTYPE 


Remarks 

The caller may Query the status of a particular environment name. The caller passes a pointer to the 
name of an environment. A flag indicating the existence of the subcommand (1 = registered, 0 = not reg- 
istered) is returned as well as the userword saved at registration. 


C Language 

/*** RxSubcomQuery - Query an environment for Existence */ 


USHORT API ENTRY RxSubcomQuery ( 
PSZ, 

PSZ, 

PUSHORT, 
double far *); 


/* Name of the Environment */ 
/* DLL Module Name */ 
/* Stor for existence code */ 
/* Stor for user word */ 
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RxSubcomQuery - 
Query Subcommand Environment Name 


Assembler Language 

5* RxSubcomQuery - Query an environment for Existence 

f 

;* ©RxSubcomQuery ^Environment, *Dllname, ^Existence, *User 

• 

• 

©RxSubcomQuery macro env.dll ,ex,usr 
©define RXSUBCOMQUERY 

©pushs env ; Name of the Environment 

©pushs dll ; DLL Module Name 

©pushs ex ; Stor for existence code 

©pushs usr ; Stor for user word 

call far ptr RXSUBCOMQUERY 
endm 
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RxSubcomRegister - 

Register Subcommand Environment 


This call allows the user to register a subcommand environment. 


RxSubcomRegister (SubComBlock) 


Parameters 

SubComBlock (PSCBLOCK) - input 

A pointer to a user-allocated SCBLOCK (see - Heading 'SCBDEFS' unknown -). 

Data Definitions 

To register a subcommand environment, a subcommand request block or SCBLOCK must be created. 
Here is the format of an SCBLOCK: 


C Language 

/*** Structure of REXX Subcommand Block (SCBLOCK) */ 


typedef struct subcomjiode { 
struct subcom_node far *next; 
PSZ scbname; 

PSZ scbdlljiame; 

PSZ scbd11j>roc; 

double scbuser; 

PFN scbaddr; 

USHORT scbmod_handle; 

USHORT $cbdrop_auth; 

PIO scbpid; 

USHORT scbsid; 

} SCBLOCK; 


/* Pointer to the next block */ 
/* Subcoin environment name */ 
/* Subcom module name */ 
/* Subcom procedure name */ 
/* User area */ 
/* Subcom environment address */ 
/* Dynalink module handle */ 
/* Permission to drop */ 
/* Process 10 of registrant */ 
/* Session ID. */ 


typedef SCBLOCK FAR *PSCBL0CK; 


Assembler Language 

;*** Structure of Rexx Subcommand Block (SCBLOCK) 


SCBLOCK struc 
next 

dd 

7 

pointer to the next block 

scbname 

dd 

? 

subcom environment name 

scbdlljiame 

dd 

? 

subcom module name 

scbdll_proc 

dd 

7 

subcom procedure name 

scbuser 

dq 

7 

user area 

scbaddr 

dd 

? 

subcom environment address 

scbmodjiandl e 

dw 

? 

dynalink module handle 

scbdrop_auth 

dw 

7 

Permission to drop 

scbpid 

dw 

? 

Pi d of Registrant 

scbsid 

SCBLOCK ends 

dw 

? 

Session ID. 

PSCBLOCK 

dd 

? i 

; Pointer to an SCBLOCK 

Within the SCBLOCK 

you must specify either: 


• For dynalink registration: the subcommand environment name (scbname), the library name 
( scbdli_name ), and the procedure name ( scbdlt _proc ); or 
» For EXE-module registration: the subcommand environment name (scbname), and the handler 
address (scbaddr). 


Where: 

scbname An ASCIIZ string to be registered as the subcommand environment name. 
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RxSubcomRegister - 
Register Subcommand Environment 


scbdlljiame 


scbdll j>roc 


scbaddr 


An ASCiiZ string specifying the library name of the dynalink library containing the sub- 
command handler. scbdlljiame is the field that REXX uses to determine if this is a 
DLL or .EXE registration. If scbdll_name is a null pointer (0), this is assumed to be an 
.EXE registration. If scbdll_name is non-null, this is assumed to be a DLL registration. 
The library name is the name supplied by the module definition file for this library. 

An ASCIIZ string specifying the procedure name of the subcommand handler. Used by 
DosGetProcAddr to get the address of the subcommand handler procedure. 

The actual address of the subcommand environment handler. This parameter is for 
use by .EXE programs supplying an internal routine as the subcommand handler. 
These handlers are "local'’ to the current process (that is, only subcommands origi- 
nating in the same process as the registration process of “local” handlers will be pre- 
sented to the handler). 


The following fields are optional: 

scbdrop_auth Drop authority. Determines which processes can drop the subcommand handler. The 
options are: 

RXSUBCOM.DROPPABLE 

Allows any process to drop this subcommand handler using the 
RxSubcomDrop call (see page 3-4). This is the default setting. 

RXSUBCOM.NONDROP 

Only a thread of execution with the same session ID and process ID 
as the thread that registered this handler will be allowed to com- 
plete a RxSubcomDrop request against this handler. 

scbuser User area to be saved with subcommand registration information. 


Returns 

0 RXSUBCOMJDK 

10 RXSUBCOMJXJP 

1002 RXSUBCOM_NOEMEM 

1003 RXSUBCOMJ3ADTYPE 


C Language 

/*** RxSubcomRegister - Register environment as Subcommand handler */ 

USHORT API ENTRY RxSubcomRegister( 

PSCBLOCK ); /* Pointer to SCBLOCK */ 


Assembler Language 

;* RxSubcomRegister - Register environment as Subcommand handler 

t 

;* ©RxSubcomRegister *$ubcomBlock 

©RxSubcomRegister macro pscb 

©define RXSUBCOMREGISTER 

©pushs pscb ; Pointer to SCBLOCK 

call far ptr RXSUBCOMREGISTER 

endm 
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Chapter 4. External Functions 


There are two types of external functions, routines written in REXX and routines written in other 
OS/2-supported languages. External functions written in REXX are not registered with REXX; they are 
found by a disk search for a file name that matches the function name being called. Functions written in 
other languages, however, must be registered. Whether they are packaged as part of an .EXE module or 
as a procedure within a dynalink library, REXX must be told where they are so that the correct invocation 
mechanism can be used. 

Note: Both kinds of external functions are subject to a standard search order for all subroutines and 
functions. 


Registering Function Packages 

The parameters needed for each kind of registration are described here. The actual interfaces for regis- 
tration and execution are described on page 4-3. 

For details on the general requirements and options for packaging API handlers, see "General 
Characteristics” on page 1-2. 

Dynamic Link Library Functions 

A dynamic link library file has a name and one or more externally callable entry points. The name and 
entry points are defined both in the function source code and in the .DEF file provided to the linker. 

Functions available in DLLs are registered by: 

REXX-vIsIble name an ASCliZ-string name which will be called within a REXX program; 

for example, 

Say My Beep (200,200) 

Dynamic Link Library an ASCliZ-string name which identifies the DLL file containing the 

requested function; for example, 

MYDLL 

The DLL file must exist in a directory included in the LIBPATH 
system-environment variable, which is set from CONFIG.SYS when 
the system is booted. 

Entry point an ASCliZ-string name which identifies the visible or available entry 

point into the DLL used to access the proper function; for example, 

USHORT API ENTRY MYENTRYP0INT(. . .) 

If multiple functions are to be accessed through the same entry 
point, the proper function name can be determined from the first 
parameter of RxFunctionCall. 

Executable Functions In Memory 

Functions that are part of executable files loaded in memory are registered by: 

REXX-Vislble Name an ASCliZ-string name which will be called within a REXX program; 

for example, 

Say MyBeep (200,200) 

Transfer address the address of a function in memory which will accept the proper 

parameters and perform the required operations for the function 
call; for example, 

(PSZ) (&MyFunction()) 
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Writing External Functions 


Here is the format for writing an external function: 

SHORT API ENTRY my_rexx_f unction (PSZ, SHORT, PRXSTRING, PSZ, PRXSTRING); 


short far pascal my_rexx_f unction (name, argc, argv, queue, retstr); 


char * name; /* name the function is invoked as */ 
short argc; /* number of arguments */ 
RXSTRING far argv[]; /* argument array */ 
char far * queue; /* name of current queue */ 
RXSTRING far * retstr; /* RXSTRING for function result */ 


Where 

name 

argc 

argv 

queue 

retstr 


is the name by which the function is invoked. 

is the size of the argument list, namely the number of elements passed, 
is an array of RXSTRINGs describing the arguments, 
is the name of the queue to be used by the function, 
is the result RXSTRING; see "Returning Result Values." 


Functions must return a valid RXSTRING for the retstr parameter. If there is no value to return from the 
function, an empty RXSTRING can be used. If called as a function and no value is returned, the inter- 
preter will generate error 44, “Function did not return data." 


For an RXSTRING in huge form, the storage area must be created by a call to DosAllocHuge(). For 
RXSTRING in short form, the storage area must be created by a call to DosAllocSegQ. The interpreter 
will destroy any RXSTRING passed to it as a return value from a function call. Any program that wishes to 
maintain the information passed to REXX must create its own copy before transferring control back to the 
interpreter. 


Returning Result Values 

Subcommands and external functions are capable of returning RXSTRING result strings which are 
returned in the special variable RC for subcommands or in RESULT for external subroutines (external 
function results will be processed in line to the calling clause). To accomplish this, function and subcom- 
mand handlers will be passed an address to an RXSTRING of length 250 in the REXX interpreter's storage 
space. The processor can use this RXSTRING or return a far pointer to memory allocated by 
DosAllocSeg or DosAllocHuge. If this memory is allocated by a process other than the one in which the 
interpreter is running (for example, during execution of another program called by the function), it must 
be made available to the interpreter via a call to DosGiveSeg. The interpreter frees this storage after 
copying the result string into the appropriate interpreter storage. 

The possible RXSTRING result values are: 

• A null strptr (that is, strptr = zero) is assumed to represent no result returned. 

• A strength of zero with a valid strptr is assumed to represent a zero-length result returned. 

• A non-zero strlength with a valid strptr is assumed to represent a valid result returned. 


Calling External Functions 

Functions registered with REXX by address can only be used in a program running in the same process, 
that is, one having the same process identification. It is possible to have different functions registered 
with the same REXX-visible name, as long as they are all registered by address and are all registered 
from different processes. If, however, a function is registered as part of a dynamic link library, it is a 
global function, and its REXX-visible name cannot be repeated. 
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External Interface Calls 


The calls that you use for registering and manipulating function packages are: 

• RxFunctionCall (Call Function) 

• RxFunctionDeregister (Remove Function) 

• RxFunctionQuery (Query List of Functions) 

• RxFunctionRegister (Register Function). 

Sample External Function Calls 

#define NULL_PTR OL 

char *func, *dl1 , *proc, *queue; 

ushort argc; 

short rc, return_code; 

RXSTRING *argv, retstr; 

return_code » RxFunctionRegister (func, dll, proc, RX_DYNALINK) ; 

return _code = RxFunctionRegister (func, NULL_PTR, (PSZ) &my_rexx_function, RX_CALLENTRY) ; 
return_code = RxFunctionDeregister (func); 
return_code = RxFunctionQuery (func); 

return_code B RxFunctionCall (func, argc, argv, queue, &rc, Sretstr); 

The calls are described on the remaining pages of this chapter. 
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RxFunctionCall - 
Call External Function 


This call allows the user to call a function registered with REXX as an external function. 


RxFunctionCall (FuncName, ArgCount, ArgLIst, RetVal, Result, QueueName) 


Parameters 

FuncName (PSZ) - input 

A pointer to the ASCIIZ string containing the name of the external function to call. 

ArgCount (USHORT) - input 

The number of arguments being passed to the function. 

ArgLIst (PRXSTRtNG) - input 

A pointer to the list of arguments being passed to the function. 

RetVal (PUSHORT) - output 

A pointer to the address of a place for the function to put a return code. 

Result (PRXSTRING) - output 

A pointer to the descriptor for the result string from the function (See “Returning Result Values” on 
page 4-2). 

QueueName (PSZ) - input 

A pointer to the default queue for use by the function. 

Returns 

0 RXFUNC_OK 

30 RXFUNC_NOTREG 

40 RXFUNC_MODNOTFND 

50 RXFUNC_ENTNOTFND 

Remarks 

The function invoked will be the most recent registration of FuncName, with certain restrictions. If a func- 
tion is found with a registered name of FuncName, but is not available to the current process, the search 
for the function will continue as if no registration had been found. 

A function registered with the RXFUNC_DYNALINK flag will be executed if it is the first valid registration 
found. 


C Language 

/*** RxFunctionCan - Call a function in the AFT */ 

USHORT API ENTRY RxFunctionCall ( 

V 
*/ 
*/ 
*/ 
*/ 
*/ 


lendif /* INCL_RXFUNC */ 


PSZ, 

USHORT, 

PRXSTRING, 

PUSHORT, 

PRXSTRING, 

PSZ ); 


/* Name of function to call 
/* Number of arguments 
/* Array of argument strings 
/* RC from function called 
/* Storage for returned data 
/* Name of active data queue 
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RxFunctionCall — 
Call External Function 


Assembler Language 

;* RxFunctionCall - Call a function in the AFT 

e 

t 

;* ^RxFunctionCall *Name,Argc,*Argv,*rc,*ret,*Qname 
« 

(^RxFunctionCall macro name, argc,argv,rc, ret, qname 
^define RXFUNCTIONCALL 


Gpushs 

name 

; Name of function to call 

Opushw 

argc 

; Number of arguments 

Opushs 

argv 

; Array of argument strings 

Opushs 

rc 

; RC from function called 

Opushs 

ret 

; Storage for returned data 

Opushs 

qname 

; Name of active data queue 


call far ptr RXFUNCTIONCALL 
endm 

endif ;INCL_RXFUNC 
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RxFunction Deregister - 
Remove Function 


This call allows the user to remove a function. 


RxFunctionDereglster (FuncName) 


Parameters 

FuncName (PSZ) - input 

A pointer to the ASCIIZ string containing the name of the external function to remove. 

Returns 

0 RXFUNCOK 

30 RXFUNC.NOTREG 

C Language 

/*** RxFunctionDeregister - Delete a function from the AFT */ 

USHORT API ENTRY RxFunctionDeregister ( 

PSZ ); /* Name of function to remove */ 


Assembler Language 

;* RxFunctionDeregister - Delete a function from the AFT 
* 

;* ^RxFunctionDeregister *Name 
# 

^RxFunctionDeregister macro name 

^define RXFUNCTIONDEREGISTER 

@pushs name ; Name of function to remove 

call far ptr RXFUNCTIONDEREGISTER 

endm 
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RxFunctionQuery - 
Query List of Functions 


This call allows the user to query the list of available functions within a particular function. 


RxFunctionQuery (FuncName) 


Parameters 

FuncName (PSZ) - input 

A pointer to the ASCIIZ string containing the name of the external function to search for. 

Returns 

0 RXFUNC_OK 

30 RXFUNC.NOTREG 

Remarks 

This function will return RXFUNC_OK only if the requested function is available for calling by the current 
process. If a function is found with a registered name of FuncName , but is tagged as belonging to a dif- 
ferent process, the search for the function will continue as if no registration had been found. 

C Language 

/*** RxFunctionQuery - Scan the AFT for a function */ 

USHORT API ENTRY RxFunctionQuery ( 

PSZ ); /* Name of function to find */ 


Assembler Language 

;* RxFunctionQuery - Scan the AFT for a function 

;* ^RxFunctionQuery *Name 

^RxFunctionQuery macro name 

@define RXFUNCTIONQUERY 

Gpushs name ; Name of function to find 

call far ptr RXFUNCTIONQUERY 

endm 
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RxFunctionRegister 
Register Function 


This call allows the user to register a function either as a dynalink procedure or as an address in a 
program in memory. 


RxFunctionRegister (FuncNavne, ModuleName, EntryPoint, ModuleType) 


Parameters 

FuncName (PSZ) - input 

A pointer to the ASCIIZ string containing the name of the external function. 

ModuleName (PSZ) - input 

A pointer to the ASCIIZ string containing the name of the dynamic link library for the function. 
EntryPoint (PSZ) - input 

A pointer to the ASCIIZ string containing the name of the dynalink procedure to perform the function. 
ModuleType (USHORT) - input 

A flag indicating in what type of module the function resides. The valid registration-type identifiers 
are: 

RXFUNCJ>YNALINK 

indicates that the function is available in a dynamic link library. 

RXFUNC_CALLENTRY 

indicates that the function is registered as an entry point in memory. 


Returns 

0 RXFUNC_OK 

10 RXFUNC_DEFINED 

20 rxfunc’nomem 

Remarks 

When ModuleType is RXFUNCCALLENTRY, a function address in the current program is registered. 
Because the third parameter is defined as a PSZ, the address of the function will have to be cast on the 
call. The ModuleName parameter is ignored for this type of registration. 


C Language 

/*** RxFunctionRegister - Register a function in the AFT */ 


USHORT API ENTRY RxFunctionRegister ( 


PSZ, 

/* 

PSZ, 

/* 

PSZ, 

/* 

USHORT) ; 

/* 


Name of function to add */ 
Dll file name (if in dll) */ 
Entry in dll OR mem address*/ 
RX_DYNALINK || RX_CALLENTRY*/ 
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RxFunctionRegister - 
Register Function 

Assembler Language 

;* RxFunctionRegister - Register a function in the AFT 

;* ^RxFunctionRegister *name,*dl 1 name, *funcname, type 

^RxFunctionRegister macro name.dll »fn, type 

^define RXFUNCTIONREGISTER 

Opushs name ; Name of function to add 

Opushs dll ; Dll file name (if in dll) 

Opushs fn ; Entry in dll OR mem address 

Opushw type ; RX_DYNALINK || RX CALLENTRY 

call far ptr RXFUNCTIONREGISTER 
endm 
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Chapter 5. Macrospace Interface 


The macrospace interface can reduce the search time for REXX functions on disk by allowing a function 
image to be maintained in memory for immediate load and execution. This capability is especially useful 
for procedures and functions which are used frequently In a program, such as editor macros. 

For the REXX programmer, calling a macrospace-registered function is essentially identical to that for 
any other function call. The macrospace functions are global to all REXX procedures. The sole differ- 
ence in execution is the priority is given in the external-function search order. Functions registered in 
the macrospace can be placed in this search order to be executed before or after all other external func- 
tions. 

The REXX interpreter environment during the execution of macrospace functions is the same as if the 
functions existed in external REXX files. 


Search Order 

When a function Is registered in the macrospace through the interface functions, a flag is passed 
requesting the function’s position in the external function search order for the REXX interpreter. There 
are two valid requests for search order positioning: before all other external functions and after all other 
external functions. 

Pre-External Function Registration 

If a function is registered with the RXMACRO_SEARCH_BEFORE flag, the REXX interpreter locates that 
function before any functions existing in external REXX files or in function packages. This allows the user 
to supersede termporarily the normal execution of a function by replacing an external function without 
deleting or renaming the file or cancelling the function’s registration in function packages. 

Post-External Function Registration 

If a function is registered with the RXMACRO_SEARCH_AFTER flag, the REXX interpreter locates that 
function will be located by the REXX interpreter after any functions existing in external REXX files or in 
function packages. This allows the user to provide a default function for the REXX interpreter to use if 
some external function required by the interpreter cannot be found in an external REXX file or function 
packages. 


Storage of Macrospace Libraries 

Functions registered in the macrospace can be saved to a permanent storage file on disk for loading at a 
later date. This allows an application, such as an editor, to create its own library of frequently used func- 
tions and load the entire macrospace library into memory for fast access by the language processor. 

This macrospace library is specified by a file name. Thus, multiple macrospace function libraries can 
exist concurrently on a disk. 

Some consideration must be given to matters of storage and memory utilization. The fact that the macro- 
space interface is designed to enhance performance for external REXX functions places severe limita- 
tions on the number of restrictions imposed by the API. Therefore, the only limitations placed on the user 
are the constraints of available memory imposed by OS/2. The macrospace may grow as long as 
memory is available. However, if the macrospace grows too large (relative to the amount of available 
memory), performance of the operating system may deteriorate due to an increased number of disk 
accesses to maintain its swap file. 

Therefore, the macrospace should not be used to hold all of the functions needed by the user for daily 
normal use. A more efficient method is to maintain only those functions which the current process uses 
in the macrospace, and to either delete or omit others from the macrospace. 
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Macrospace Interface Calls 

The calls that you use for registering and manipulating functions with the macrospace interface are: 

• RxMacroChange (Change or Add Function to Macrospace) 

• RxMacroDrop (Delete Function from Macrospace) 

• RxMacroErase (Erase Functions in Macrospace) 

• RxMacroLoad (Load Functions into Macrospace) 

• RxMacroQuery (Search for Function in Macrospace) 

• RxMacroReOrder (Change Search Order in Macrospace) 

• RxMacroSave (Save Functions in Macrospace). 

The calls are described on the following pages. 
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RxMacroChange - 
Change or Add Function to Macrospace 


This call allows the user to change or add a function to the macrospace. 


RxMacroChange (FuncName, SourceFile, Position) 


Parameters 

FuncName (PSZ) - input 

A pointer to the ASCIIZ string specifying the name by which the function will be known. This function 
name must be validated to follow the REXX rules for function names; it should also correspond to 
function names Implemented as part of external function packages. 

SourceFile (PSZ) - input 

A pointer to the ASCIIZ string file specification of the disk file containing the source for this function. 
If no file extension is supplied it defaults to ".CMD.” If the full path is not specified the standard 
search is conducted (search current directory and OS/2 path). 

Position (USHORT) - input 

The flag indicating where in the external function search order for REXX this function should be 
placed. There are two possible positions: a function can be placed at the beginning of the search 
order (that is, before all other external functions), or at the end of the search order (that is, after all 
other external functions). 

Returns 

0 RXMACRO_OK 

1 RXMACRO_NO_STORAGE 

7 RXMACRO_SOURCE_NOT_FOUND 

8 RXMACRO_INVALID_POSITION 

C Language 

/*** RxMacroChange - Register a function in the Macro Space */ 

USHORT API ENTRY RxMacroChange ( 

PSZ, 

PSZ, 

USHORT ); 

Assembler Language 

;* RxMacroChange - Register a function in the Macro Space 
» 

;* ©RxMacroChange *Name,*Fi lename,flag 

©RxMacroChange macro name, f name, flag 
©define RXMACROCHANGE 
©pushs name ; Function to add/change 

©pushs fname ; Name of file to get 

©pushw flag ; Flag indicating search pos 

call far ptr RXMACROCHANGE 
endm 


/* Function to add/change */ 
/* Name of file to get function*/ 
/* Flag indicating search pos */ 
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RxMacroDrop - 

Delete Function from Macrospace 


This call allows the user to delete a function from the macrospace. 


RxMacroDrop (FuncName) 


Parameters 

FuncName (PSZ) - input 

A pointer to the ASCIIZ string specifying the name of the function to remove. 

Returns 

0 RXMACRO_OK 

2 RXMACRO_NOT_FOUND 

C Language 

/*** RxMacroDrop - Remove a function from the Macro Space */ 

USHORT APIENTRY RxMacroDrop ( 

PSZ ); /* Name of function to remove */ 

Assembler Language 

;* RxMacroDrop - Remove a function from the Macro Space 

;* ^RxMacroDrop *Name 

^RxMacroDrop macro name 

^define RXMACRODROP 

Opushs name ; Name of function to remove 

call far ptr RXMACRODROP 

endm 
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RxMacroErase - 
Erase Functions in Macrospace 


This call allows the user to erase ail functions in the macrospace. 


RxMacroErase () 


Returns 

0 RXMACRO.OK 

2 RXMACRO_NOT_FOUND 

Remarks 

There are no parameters to this function. Special care should be taken in using this function, because no 
verification is done on the deleted functions; that is, all functions are removed from the macrospace even 
if other processes use that function. 

C Language 

/*** RxMacroErase - Remove all functions 

USKORT API ENTRY RxMacroErasef 

VOID ); /* No 

Assembler Language 

5* RxMacroErase - Remove all functions from the Macro Space 

5* ^RxMacroErase 

^RxMacroErase macro 

^define RXMACROERASE 
call far ptr RXMACROERASE 
endm 


from the Macro Space */ 
Arguments. */ 
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RxMacroLoad - 

Load Functions into Macrospace 


This call allows the user to load either all functions or a subset of all functions from a file into the macro- 
space. 


RxMacroLoad (FuncCount, FuncNames, MacroLibFile) 


Parameters 

FuncCount (USHORT) - input 

The number of functions requested for loading from the source file. 

FuncNames (PSZ FAR ') - input 

A pointer to a list of ASCIIZ strings containing the names of the functions to be loaded from the file 
(number of strings in list given by FuncCount). 

MacroLibFile (PSZ) - input 

A pointer to the ASCIIZ file name string to load workspace from. 


Returns 


0 

1 

2 

4 

5 

6 


RXMACRO_OK 

RXMACRO_NO_STORAGE 

RXMACRO_NOT_FOUND 

RXMACRO_ALREADY_EXISTS 

RXMACRO_FILE_ERROR 

RXMACRO_SIGNATURE_ERROR 


Remarks 


If FuncCount is zero or FuncNames is NULL, all of the functions in the file will be loaded. 

The FuncNames parameter is a pointer to a list of pointers, similar to the argv parameter list in the 
main() function of a C-language program. 

If a request is made to load a function which already exists (that is, if there is already a function with the 
same name in the macrospace), the entire load request is discarded and the macrospace remains 
unchanged. 
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RxMacroLoad - 
Load Functions into Macrospace 


C Language 

/*** RxMacroLoad - Load Macro Space functions from a file */ 

USHORT API ENTRY RxMacroLoad ( 

USKORT, 

PSZ FAR *. 

PSZ ): 

Assembler Language 

;* RxMacroLoad - Load Macro Space functions from a file 
;* ©RxMacroLoad Argc,**Li s t of names, *Filename 

9 

©RxMacroLoad macro argc.l name, f name 

©define RXMACROLOAD 

©pushw argc ; Argument count (0==load) 
©pushs lname ; List of funct names to load 

©pushs fname ; File to load functions from 

call far ptr RXMACROLOAD 
endm 


/* Argument count (G==load all)*/ 
/* List of funct names to load */ 
/* File to load functions from */ 
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RxMacroQuery - 

Search for Function in Macrospace 


This call allows the user to search for a function in the macrospace. 


RxMacroQuery (FuncName, Position) 


Parameters 

FuncName (PSZ) - input 

A pointer to the ASCIIZ string specifying the name of the function to seek in the list of workspace 
functions. 

Position (PUSHORT) - output 

A pointer to a USHORT for return of the current search-order position of the function, if it exists. If 
the function does not exist in the macrospace, the value will not be changed. 

Returns 

0 RXMACRO_OK 

2 RXMACRO_NOT_FOUND 

C Language 

/*** RxMacroQuery - Find a function's search-order position */ 

USHORT APIENTRY RxMacroQuery ( 

PSZ, /* Function to search for */ 

PUSHORT ); /* Ptr for position flag return*/ 

Assembler Language 

;* RxMacroQuery - Find a function's search-order position 

;* (^RxMacroQuery *Name,*Flag 

^RxMacroQuery macro name, flag 

^define RXMACROQUERY 

@pushs name ; Function to search for 
@pushs flag ; Ptr for position flag 
call far ptr RXMACROQUERY 
endm 
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RxMacroReOrder - 
Change Search-Order in Macrospace 


This call allows the user to change the search-order location of a function in the macrospace. 


RxMacroReOrder {FuncName, Position) 

Parameters 

FuncName (PSZ) - input 

A pointer to the ASCIIZ string specifying the name of the function whose search order positioning is 
to be changed. 

Position (USHORT) - input 

The flag indicating where this function is placed in the external function search order for REXX. 

Returns 

0 RXMACRO_OK 

2 RXMACRO_NOT_FOUND 

8 RXMACRO_INVALID_POSITION 

C Language 

/*** RxMacroReOrder - Change a function's search-order position */ 

USHORT API ENTRY RxMacroReOrder ( 

PSZ, /* Name of fund change order */ 

USHORT ); /* New position for function */ 

Assembler Language 

;* RxMacroReOrder - Change a function's search-order position 

;* ^RxMacroReOrder *Name, Position 

^RxMacroReOrder macro name.pos 

^define RXMACROREORDER 

@pushs name ; Name of funct change order 
@pushw pos ; New position for function 

call far ptr RXMACROREORDER 
endm 


Search Order Flags 

The following are the flags which are passed to the macrospace interface to specify where a function 
should be placed in the REXX search order for external functions: 

RXMACRO_SEARCH_BEFORE place function at top of search order 
RXMACRO_SEARCH_AFTER place function at bottom of search order. 
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Rx MacroSave - 

Save Functions in Macrospace 


This call allows the user to save either all functions or a subset of all functions in the macrospace to a 
file. 


RxMacroSave (FuncCount, FuncNames, MacroLibFile) 


Parameters 

FuncCount (USHORT) - input 

The number of functions requested for saving to the file. 

FuncNames (PSZ FAR *) - input 

A pointer to a list of ASCIIZ strings containing the names of the functions to be saved to the file 
(number of strings in list given by FuncCount). 

MacroLibFile (PSZ) - input 

A pointer to the ASCIIZ filename string to save the workspace to. If file exists it is overwritten. If file 
does not exist it is created. 

Returns 

0 RXMACRO_OK 

2 RXMACRO_NOT_FOUND 

3 RXMACRO_EXTENSION_REQUIRED 

5 RXMACRO_FILE_ERROR 

Remarks 

If FuncCount is zero or FuncNames is NULL, all of the functions in the macro space are saved. 

The FuncNames parameter is a pointer to a list of pointers, similar to the argv parameter list in the 
main() function of a C program. 

C Language 

/*** RxMacroSave - Save Macro Space functions to a file */ 

USHORT API ENTRY RxMacroSave ( 

USHORT, 

PSZ FAR *, 

PSZ ); 

Assembler Language 

;* RxMacroSave - Save Macro Space functions to a file 

;* ©RxMacroSave Argc,**Listof names, *Filename 

©RxMacroSave macro argc.l name, f name 

©define RXMACROSAVE 

©pushw argc ; Argument count (0==save) 

©pushs lname ; List of funct names to save 

©pushs fname ; File to save functions in 

call far ptr RXMACROSAVE 
endm 


/* Argument count (0==save all)*/ 
/* List of funct names to save */ 
/* File to save functions in */ 
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Chapter 6. Variable Pool Interface 


Applications use the variable pool interface to manipulate the variable pool of the currently active REXX 
procedure. Here are C- and Assembler-language examples of variable pool APIs. 


C Language 

/*** Shared Variable Pool Interface */ 

/*** Function Codes for Variable Pool Interface (shvcode) */ 


Idefine RXSHV SET 

0x00 

/* Set variable from given value 

*/ 

#define RXSHV FETCH 

0x01 

/* Copy value of variable to buffer 

*/ 

Idefine RXSHV OROPV 

0x02 

/* Drop variable 

V 

#define RXSHV~SYSET 

0x03 

/* Symbolic name Set variable 

V 

#define RXSHV SYFET 

0x04 

/* Symbolic name Fetch variable 

V 

#define RXSHV SYDRO 

0x05 

/* Symbolic name Drop variable 

*/ 

Idefine RXSHV NEXTV 

0x06 

/* Fetch "next" variable 

*/ 

#define RXSHV PRIV 

0x07 

/* Fetch private information 

*/ 

Idefine RXSHV^EXIT 

0x08 

/* Set function exit value 

*/ 

/*** Return Code Flags for Variable Pool Interface (shvret) */ 


Idefine RXSHV OK 

0x00 

/* Execution was OK 

*/ 

Idefine RXSHV NEWV 

0x01 

/* Variable did not exist 

*/ 

Idefine RXSHV LVAR 

0x02 

/* Last var transferred via SHVNEXTV 

*/ 

Idefine RXSHV TRUNC 

0x04 

/* Truncation occurred during Fetch 

*/ 

Idefine RXSHV BADN 

0x08 

/* Invalid variable name 

*/ 

Idefine RXSHV MEMFL 

0x10 

/* Out of memory failure 

V 

Idefine RXSHV~BADF 

0x80 

/* Invalid function code (shvcode) 

V 

/*** Structure of Shared Variable Request Block (SHVBLOCK) */ 


typedef struct shvnode { 

struct shvnode FAR *shvnext; 

/* Chain pointer to the next block 

V 

RXSTRING 

shvnatne; 

/* Pointer to the variable name 

V 

RXSTRING 

shvvalue; 

/* Pointer to the value buffer 

V 

ULONG 

shvnatnelen; 

/* Length of the name value 

V 

ULONG 

shvvaluelen; 

/* Length of the fetch value 

*/ 

UCHAR 

shvcode; 

/* Individual function code 

V 

UCHAR 

shvret; 

/* Individual return code flags 

V 


} SHVBLOCK; 

typedef SHVBLOCK FAR *PSHVBLOCK; 

SHORT API ENTRY RxVar ( 

PSHVBLOCK) ; /* Pointer to a list of SHVBLOCK’ s */ 

#endif /* INCL_RXSHV */ 
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Assembler Language 


;*** Shared Variable Pool Interface 

ifdef INCL_RXSHV 


;*** Function 

Codes for Variable Pool Interface (shvcode) 

RXSHV SET 

equ 

OOOOh 

Set var from given value 

RXSHV FETCH 

equ 

000 Ih 

Copy value of var to buffer 

RXSHV DROPV 

equ 

00Q2h 

Drop variable 

RXSHV SYSET 

equ 

OO03h 

Symbolic name Set variable 

RXSHV SYFET 

equ 

0004 h 

Symbolic name Fetch variable 

RXSHV SYDRO 

equ 

00Q5h 

Symbolic name Drop variable 

RXSHV NEXTV 

equ 

0QQ6h 

Fetch “next" variable 

RXSHV PRIV 

equ 

0007 h 

Fetch private information 

RXSHV EXIT 

equ 

0008h 

Set function exit value 

;*** Return Code Flags for Variable Pool Interface (shvret) 

RXSHV OK 

equ 

OOOOh 

Execution was OK 

RXSHV NEWV 

equ 

OOOlh 

Variable did not exist 

RXSHV LVAR 

equ 

0002h 

Last var trans via SHVNEXTV 

RXSHV TRUNC 

equ 

0004h 

Truncation occurred-Fetch 

RXSHV BADN 

equ 

0008h 

Invalid variable name 

rxshv“memfl 

equ 

OOlOh 

Out of memory failure 

RXSHV BADF 

equ 

0080h 

Invalid funct code 

RXSHV JOAVL 

equ 

0090h 

Interface not available 

;*** Structure 

of Shared Variable Request Block (SHVBLOCK) 

SHVBLOCK struc 

shvnext 

dd 

? 

Pointer to the next block 

shvname 

dd 

? 

Pointer to the name buffer 

shvvalue 

dd 

? 

Pointer to the value buffer 

shvname 1 en 

dd 

7 

Length of the name value 

shvvaluel en 

dd 

7 

Length of the fetch value 

shvcode 

db 

7 

Function code for this block 

shvret 

SHVBLOCK ends 

db 

7 

Individual Return Code Flags 

PSHVBLOCK 

dd 

7 



;* RxVar - Request Variable Pool Service 

;* ©RxVar *Shared Variable Request Block 
» 

©RxVar macro shv 

©define RXVAR 

©pushs shv ; Pointer to list of SHVBLOCKs 

call far ptr RXVAR 

endm 

endif ;INCL_RXSHV 
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RxVar - 

Pass Request Blocks to Variable Pool 


This call allows the user to pass a linked list of shared variable request blocks to the variable pool. 


RxVar (RequestBlockList) 


Parameters 

RequestBlockList (PSHVBLOCK) - Input 

A pointer to a linked list of shared variable request blocks. Each request block can specify a dif- 
ferent operation to be performed by the interpreter. Each request block is processed in turn; control 
returns to the caller after the last block or after a severe error. In this manner, the interpreter can 
perform multiple operations by issuing only one call. 

An integer return code will be returned from the RxVar call and will contain the return code from the 
entire set of requests. Return codes for each individual shared variable request block is found in a 
field of the block. 

Returns 

0 or positive Entire shared variable request block list was processed. The return code is 

the composite OR of the low-order 6 bits of the shvret bytes. 

-1 Invalid entry conditions. 

-2 Insufficient storage was available for a request set. Processing was aborted 

(some of the request blocks may remain unprocessed - their shvret bytes will 
be unchanged). 

-3 The variable pool interface was not enabled when this call was issued. 

127 The RxVar routine was not found. Equivalent to DosGetProcAddr 

error_proc_not_found. 

C Language 

/*** RxVar - Request Variable Pool Service */ 

USHORT API ENTRY RxVar( 

PSHVBLOCK); /* Pointer to list of SHVBLOCKs*/ 

fendif /* INCL_RXSHV */ 

Assembler Language 

;* RxVar - Request Variable Pool Service 

;* @RxVar ^Shared Variable Reqest Block 

@RxVar macro shv 

^define RXVAR 

@pushs shv ; Pointer to list of SHVBLOCKs 

cal 1 far ptr RXVAR 

endm 
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Interface Types 


Three of the variable pool interface functions — set, fetch, and drop — have dual interfaces, the symbolic 
and the direct. 

Symbolic Interface 

The symbolic interface refers to normal REXX substitution when interpreting variables. Variable names 
are valid REXX symbols (in mixed case if desired) including compound symbols. The functions that use 
the symbolic interface are RXSHV_SYSET, RXSHV_SYFET, and RXSHV_SYDRO. 


Direct Interface 

The direct interface uses no substitution or case translation. Simple symbols must be valid REXX vari- 
able names: in uppercase only and not starting with a digit or a period. Compound symbols, however, 
allow any characters permitted in symbols, including lowercase characters and blanks, following a valid 
REXX stem. The direct interface is used by RXSHV.SET, RXSHV_FETCH, RXSHVJ>ROP, RXSHV.NEXTV, 
RXSHVJ>RIV, and RXSHV_EXIT. 


Shared Variable Functions 

This section describes the actions for each function code. 

Notes: 

1. The terms value length, value pointer , name length and name pointer will be used generically in the 
following definitions to describe information derived from the shvvalue and shvname RXSTRING 
structures. 

2. In general terms, the RXSTRING structures shvname and shvvalue are used to describe the memory 
buffers being passed through the variable pool interface. The lengths shvnamelen and shvvaluelen 
are the actual lengths of data processed. 

Setting Variables 

RXSHV_SET and RXSHV_SYSET 

The name pointer and length describes the name of the variable to be set, and the value pointer and 
length describes the value which is assigned to it. The name is validated to ensure that it does not 
contain invalid characters, and the variable is then set from the value given. If the name is a stem, all 
variables with that stem are set, just as though this was a REXX assignment. RXSHV_NEWV is set if the 
variable did not exist before the operation. 

Fetching Variables 

RXSHV_FETCH and RXSHVSYFET 

The name pointer and length describe a buffer containing the name of the variable to be fetched; 
shvnamelen is the length of the name within the buffer. The value pointer and length describe a buffer to 
receive the value of the specified variable. The name is validated to ensure that it does not contain 
invalid characters, and the variable is then located and copied to the buffer. The total length of the vari- 
able is put into shvvaluelen. If the value was truncated (because the buffer was not big enough) the 
RXSHVJTRUNC bit is set. If the variable is shorter than the length of the buffer, no padding takes place. 

If the name is a stem, the initial value of that stem (if any) is returned. 

RXSHVNEWV is set if the variable did not exist before the operation, and in this case the value copied to 
the buffer is the derived name of the variable, such as after substitution. See “Notes and Limits” on 
page 6-6 for additional information. 
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RXSHV_NEXTV 

(Fetch next variable.) This function may be used to search through all the variables known to the inter- 
preter (that is, all those of the current generation, excluding those 41 hidden” by PROCEDURE 
instructions). The order in which the variables are revealed is not specified. 

The interpreter maintains a pointer to its list of variables. This is reset to point to the first variable in the 
list whenever a host command is issued, or any function other than RXSHV_NEXTV is executed by way of 
the variable pool interface. 

Whenever a RXSHV_NEXTV function is executed the name and value of the next available variable are 
copied to two buffers supplied by the caller. 

The name pointer and length describe a buffer into which the name is copied. The total length of the 
name is returned in shvnamelen t and if the name was truncated (because the buffer was not big enough) 
the RXSHVJTRUNC bit is set. If the name is shorter than the length of the buffer, no padding takes place. 
The value of the variable is copied to the user's buffer area using the same protocol as for the Fetch 
operation. 

If shvret has RXSHV__LVAR set, the end of the list of known variables has been found, the internal pointers 
have been reset, and no valid data has been copied to the user buffers. 

If RXSHVJTRUNC is set, either the name or the value has been truncated. 

By repeatedly executing the RXSHV_NEXTV function (until the RXSHV_LVAR flag is set) a user program 
may locate all the REXX variables of the current generation. See “Notes and Limits" on page 6-6 for 
additional information. 

RXSHV_PRIV 

(Fetch private information.) This interface is similar to the RXSHV_FETCH interface, except that the name 
refers to certain fixed information items that are available. The entire name must be specified for the 
fetch to occur. The following names are recognized: 

PARM The number of parameters (arguments) supplied to the procedure will be placed in the 
caller's buffer. The number will be formatted as a character string. 

PARM.n The Nth parameter (argument) string will be placed in the caller’s buffer. If the Nth param- 
eter (argument) was not supplied to the program (whether omitted, null, or fewer than N 
parameters were specified), a null string will be returned. 

Note: PARM.1 will return the same result as ARG. 

QUENAME Fetch data queue name. The name of the currently active data queue is copied to the user's 
buffer. 

SOURCE Fetch source string. The source string, as described for /REF37/, is copied to the user’s 
buffer. 

VERSION Fetch version string. The version string, as described for /REF38/, is copied to the user’s 
buffer. 

See “Notes and Limits’’ on page 6-6 for additional information. 

Dropping Variables 

RXSHV_DROPV and RXSHV_SYDRO 

The name pointer and length describes the name of the variable to be dropped. The value pointer and 
length are not used. The name is validated to ensure that it does not contain invalid characters. The 
variable, if it exists, is dropped. If the name given is a stem, all variables starting with that stem are 
dropped. 
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Setting an Exit Return Value 

RXSHV_EXIT 

Set function or exit return value. An external function written in a language other than REXX or a system 
exit must have the capability of returning an exit value. A single call is allowed for each exit. The value 
passed on this call is treated like the expression of a RETURN instruction. This interface is identical to 
the RXSHV_SET interface, except that no name is specified. The RXSHV_EXIT interface is only valid 
during processing of an external function or a system exit that allows a string value to be returned. 


Notes and Limits 

• The full interface is enabled only during the execution of commands (including CMD subcommands), 
external routines (functions and subroutines), and some system exits (RXINIT, RXTER, RXCMD, and 
RXFNC). It is enabled for RXSHV_EXIT operations only from exits that allow a character string to be 
returned (RXHLT, RXMSQ, RXSIO). An attempt to call the RxVar entry point when it is not enabled 
will result in a return code of -3 (RxVar not enabled). 

• On all fetch-type requests, it is allowable not to specify return buffers on the cail and have the REXX 
interpreter allocate and give appropriate memory to the caller. On RXSHV_FETCH, RXSHV_SYFET, 
and RXSHV_PRIV, the value buffers may be left for REXX to allocate. On RXSHV_NEXTV, the value 
and the name buffers may be allocated by REXX. 

To have REXX supply name buffers, set shvname to an empty string for the call. REXX will allocate a 
memory segment, set up the name pointer and length, and set shvnamelen to the length of the name 
returned. This memory (that is, the far pointer stored in the shvname RXSTRING) must be freed by 
the user via DosFreeSeg. 

To have REXX supply value buffers set shvvalue to an empty string for the call. The REXX interpreter 
will allocate segments for the value buffer. The value pointer and length will describe segments as 
appropriate for the size of the buffer returned. The total length of the requested variable’s contents 
is returned in shvvaluelen . This memory must be freed by the user via DosFreeSeg for the selector 
stored in the shvvalue RXSTRING. 

Note that by allowing REXX to supply these buffers a RXSHV_TRUNC condition will not occur. 
However, it is possible to get RXSHVJAEMFL errors for these operations. If RXSHV_MEMFL occurs 
no memory will have been allocated for that SHV_BLOCK operation. 

• Only the main thread of a REXX application is allowed to access the REXX variable pool. Applica- 
tions may create and use new threads in the course of performing their function, but only the original 
thread that started the application may interface to the REXX variable pool. 
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Chapter 7. System Exits 


The system exits interface allows REXX to operate under a user-defined environment. When these exits 
are used, certain system-dependent interpreter activities can be executed as calls to routines provided 
by the caller of the interpreter, instead of by the interpreter itself. Except as provided for here, the inter- 
preter does not allow the results of the program being interpreted to be affected by these exits. 

There are exits for: 

• The administration of resources, at the beginning and end of interpretation 

• Assisted linkages to general classes of external facilities, such as functions 

• Special language features, such as I/O to standard resources 

• Polling for external interrupts and conditions. 

As happens with subroutine and external-function handlers, system exit routines can be packaged either 
as dynalink libraries or as .EXE modules. 

For details on the requirements and options for packaging API handlers, see “General Characteristics'’ 
on page 1-2. 


Writing System Exit Handlers 

This is an example of a system exit handler: 
short pascal far my_sysexit ( 

short func, /* integer code defining the exit function */ 

short subfunc, /* integer code defining the exit sub-function */ 
char far *parm; /* function dependent control block */ 

Entry Conditions 

All exits are passed the following three parameters on entry: 

• The integer code for the exit being invoked 

• The subfunction code for the exit 

• A far pointer to the exit parameter list. 

The parameter list pointed to by the third parameter contains information specific to the exit being 
invoked. See the exit descriptions that follow for the format of the parameter list for each exit. Note that 
some of the exits do not have any additional parameters. For those exits, the parameter list pointer will 
be null. 

Exit Conditions 

On return from the exit, the integer return value indicates the results of the exit call and the parameter 
list will have been updated appropriately. The value of the return code can signal one of the three fol- 
lowing actions: 

0 successful handling of the service. The parameter list has been updated as appropriate for 
that exit. 

1 exit chooses not to handle the service request. The interpreter will handle the request 
through the default means. 

-1 a fatal error occurred during processing of this request. REXX error 48, “Failure in system 

service," will be raised. 

As an example, suppose you create a routine to process output from the SAY instruction: 

• If your exit routine returns 1, SAY processing continues in the normal manner and the REXX inter- 
preter displays the output string on the screen as usual. 
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• If your exit routine returns 0, the interpreter assumes that your exit routine has performed all 
required output. It therefore bypasses SAY processing and does not display the output string. 

• If your exit routine returns -1, the interpreter halts with error 48, “Failure in system service.” 

For many of the exits, an arbitrary length character string may be passed back to the interpreter using 
the SHVEXIT function of the RxVar routine. This routine may only be called once for each invocation of 
the exit to return a value. 

Identifying Handlers to REXX 

System exit handlers must be registered with REXX by the RxExitRegister call before they may be used. 
This process is only used to give REXX an easy way to handle the routing of exit calls. The registration of 
system exit handlers is similar to the registration of subcommand handlers (the two processes both use 
the REXX SCBLOCK), but only the registration is similar. The calling conventions and handling of system 
exits is different from subcommands. See the REXXSAA.H file for C-language definitions and the 
REXXSAA.INC file for Assembler-language definitions of the RxExitRegister, RxExitQuery, and 
RxExitDrop functions. 

Enabling System Exits 

The interpreter exits are defined on invocation of the interpreter by the sysexit parameter of the call to 
the REXX interpreter. The sysexit parameter is a pointer to an array of RXSYSEXIT structures. Each 
RXSYSEXIT in the array consists of an INT code identifying the exit to be enabled and a pointer to an 
ASCIIZ string defining the name of a registered system exit environment that supplies the system exit 
routine handler. Create an extra RXSYSEXIT element and assign the code to RXENDLST to indicate the 
end of the system exit list. 


System Exit Interface Calls 


The calls for the system exit interface are similar to some calls for the subcommand environment inter- 
face. Chapter 3, Subcommand Interface describes the subcommand environment interface calls. The 
parameters and return codes are identical; only the call names are different. The following table com- 
pares the two sets of calls: 


System Exit Call 

RxExitDrop 


RxExitQuery 


RxExitRegister 


Purpose Subcommand Call 

Allows user to drop a system RxSubcomDrop 

exit environment 

Allows user to query a system RxSubcomQuery 
exit environment name 


Read About It On 

Page 3-4 

Page 3-8 


Allows user to register a RxSubcomRegister Page 3-10 

system exit environment 


Exits 

The following examples, in C and Assembler languages, show how exits may be specified in the list with 
the exit code and subcode definitions. 
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C Language 

/* System Exit function and sub-function definitions */ 


#define 

RXENDLST 

0 

/* 

End of exit list. 

*/ 

Idefine 

RXFNC 2 


/* 

Process external functions. 

*/ 

Idefine 

RXFNCCAL 

1 

/* 

Currently the only subcode value. 

*/ 

Idefine 

RXCMD 3 


/* 

Process host commands. 

*/ 

Idefine 

RXCMDHST 

1 

/* 

Currently the only subcode value. 

*/ 

Idefine 

RXMSQ 4 


/* 

Manipulate queue. 

*/ 

#define 

RXMSQPLL 

1 

/* 

Pull a line from queue 

*/ 

#define 

RXMSQPSH 

2 

/* 

Place a line on queue 

V 

#define 

RXMSQSIZ 

3 

/* 

Return number of lines on queue 

*/ 

Idefine 

RXMSQNAM 

20 

/* 

Set active queue name (OS/2 only) 

V 

#define 

RXSIO 5 


/* 

Session I/O. 

V 

#define 

RXSIOSAY 

1 

/* 

SAY a line to STDOUT 

*/ 

Idefine 

RXSIOTRC 

2 

/* 

Trace output 

*/ 

Idefine 

RXSIOTRD 

3 

i* 

Read from session char stream 

*/ 

Idefine 

RXSIODTR 

4 

/* 

DEBUG read from session char stream*/ 

#define 

RXSIOTLL 

5 

/* 

Return line length (N/A for OS/2) 

*! 

Idefine 

RXHLT 7 


r 

Halt processing. 

*/ 

#define 

RXHLTCLR 

I 

/* 

Clear HALT indicator 

V 

#define 

RXHLTTST 

2 

/* 

Test HALT indicator 

*/ 

Idefine 

RXTRC 8 


/* 

Test external trace indicator. 

V 

Idefine 

RXTRCTST 

1 

/* 

Currently the only subcode value. 

*/ 

Idefine 

RXINI 9 


/* 

Initialization processing. 

*/ 

Idefine 

RX INI EXT 

1 

r 

Currently the only subcode value. 

*/ 

Idefine 

RXTER 10 


/* 

Termination processing. 

*/ 

Idefine 

RXTEREXT 

1 

/* 

Currently the only subcode value. 

V 

Idefine 

RXNOOFEXITS 

11 

/* 

1 more than largest exit number. 

V 


typedef unsigned char far * PEXIT ; /* pointer to exit parameter block*/ 


Assembler Language 


System Exit function and sub-function definitions 


RXENDLST 

equ 

0 

RXFNC 

equ 

2 

RXFNCCAL 

equ 

1 

RXCMD 

equ 

3 

RXCMDHST 

equ 

1 

RXMSQ 

equ 

4 

RXMSQPLL 

equ 

1 

RXMSQPSH 

equ 

2 

RXMSQSIZ 

equ 

3 

RXMSQNAM 

equ 

20 

RXSIO 

equ 

5 

RXSIOSAY 

equ 

1 

RXSIOTRC 

equ 

2 

RXSIOTRD 

equ 

3 

RXSIODTR 

equ 

4 

RXSIOTLL 

equ 

5 

RXHLT 

equ 

7 

RXHLTCLR 

equ 

1 

RXHLTTST 

equ 

2 

RXTRC 

equ 

8 

RXTRCTST 

equ 

1 

RXINI 

equ 

9 

RXINIEXT 

equ 

1 

RXTER 

equ 

10 

RXTEREXT 

equ 

1 

RXNOOFEXITS 

equ 

11 

PEXIT 

dd 

? 


; End of exit list. 

; Process external functions. 
; subcode value. 

; Process host commands. 

; subcode value. 

; Manipulate queue. 

; Pull a line from queue 
; Place a line on queue 
; Return num of lines on 
; Set active queue name 
; Session I/O. 

; SAY a line to STDOUT 
; Trace output 
; Read from char stream 
; DEBUG read from char stream 
; Return linelength(N/A OS/2) 
; Halt processing. 

; Clear HALT indicator 
; Test HALT indicator 
; Test ext trace indicator. 

; subcode value. 

; Initialization processing. 

; subcode value. 

; Termination processing. 

; subcode value. 

; 1 + largest exit number. 

; ptr to exit parameter block 



Exit Characteristics 

Each exit has the following specific characteristics: 

• The occasions when the exit is called, if provided. 

• The default action to be taken when the exit is not provided. 

• The parameter list for the exit. This parameter list is additional to the subcode, which is always 
passed. 

• The action to be taken by the exit. 

• The continuation actions to be taken by the interpreter after return from the exit. 

• Whether the variable pool interface is enabled during the exit (It is enabled only for RXCMD, 
RXFUNC, RX1NI, and RXTER; disabled during processing of all other exits.) 

For many of these exits, an arbitrary length character string may be passed back through an RXSTRING 
in the parameter block. REXX will initialize the RXSTRING to an empty string before calling the exit. 

If an exit returns a value in its parameter block and through the RXSHV_EXIT function of the RxVar 
routine, REXX uses the value set by the call to RxVar. See "Setting an Exit Return Value" on page 6-6 for 
details about using RXVAR and the functions available for exits. 


Exit Definitions 

The remainder of this chapter defines the following exit services and their subfunctions: 

• RXFNC (Process External Functions) exit service 

RXFNCCAL (Process External Functions) 

• RXCMD (Process Host Commands) 

RXCMDHST (Process Host Commands) 

• RXMSQ (Manipulate Queue) exit service 

RXMSPQLL (Pull Line from Queue) 

RXMSQPSH (Place Line on Queue) 

RXMSQSI2 (Return Number of Lines in Queue) 

RXMSQNAM (Set Name of Active Queue) 

• RXSIO (Session I/O) exit service 

RXSIOSAY (Output Result of SAY Instruction) 

RXSIOTRC (TRACE Output Processing. Call to Output TRACE Results) 
RXSIOTRD (Read From STDIN Stream) 

RXSIODTR (Debug Read) 

• RXHLT (Halt Processing) exit service 

RXHLTCLR (Clear Halt Indicator) 

RXHLTTST (Test Halt Indicator) 

• RXTRC (Test External Trace Indicator) exit service 

RXTRCTST (Test External Trace Indicator) 

• RXINI (Initialization Processing) exit service 

RXINIEXT (Initialization Processing) 

• RXTER (Termination Processing) exit service 

RXTEREXT (Termination Processing) 
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RXFNC - 

Process External Functions 


This service supports one subfunction, RXFNCCAL. The request code for this subfunction is specified by 
the second parameter. 

RXFNCCAL — Process external functions 

When called 

When interpretation is about to call an external routine. 

Default action 

Call the routine. 

Action 

Call the routine, if possible. 

Continuation 

If indicated by the return conditions, raise error 40, 43 or 44. Resume interpretation. 

C Language 

/*** Subfunction RXFNCCAL - External Function Calls */ 

typedef struct { 
struct { 


unsigned rxfferr : 1; 

/* Invalid call to routine. 

*/ 

unsigned rxffnfnd : 1; 

/* Function not found. 

*/ 

unsigned rxffsub : 1; 

/* Called as a subroutine if 

V 



/* set. Return values are 

*/ 



/* optional for subroutines. 

*/ 



/* required for functions. 

*/ 

} rxfnc_flags ; 




PUCHAR 

rxfnc_name; 

/* Pointer to function name, 

V 

USHORT 

rxfnc_namel ; 

/* Length of function name. 

V 

PUCHAR 

rxfnc_que; 

/* Current queue name. 

*/ 

USHORT 

rxf nc_que1 ; 

/* Length of queue name. 

*/ 

USHORT 

rxfnc_argc; 

/* Number of args in list. 

V 

PRXSTR1NG 

rxfnc_argv; 

/* Pointer to argument list. 

*/ 



/* List mimics argv list in 

*/ 



/* REXXSAA - array of 

*/ 



/* RXSTRINGs. 

*/ 

RXSTRING 

rxfncjretc; 

/* Return value. 

*/ 


} RXFNCCAL_PARM; 


Chapter 7. System Exits 7-5 




RXFNC - 

Process External Functions 


Assembler Language 


;*** Subfunction RXFNCCAL - External Function Calls 


rxfferr 

db 

? 

* Invalid call to routine. 

rxffnfnd 

db 

? 

* Function not found. 

rxffsub 

db 

? 

* Called as a subroutine if 




* set. Return values are 


; * optional for subroutines, 

; * required for functions. 

RXFNC_FIELD$ RECORD rxfferr:l,rxffnfnd:l,rxffsub:l,pad:13 


RXFNCCAL_PARM struc 

rxfnc_flags 

rxfncjiame 

rxfncjiamel 

rxfnc_que 

rxfnc_quel 

rxfnc_argc 

rxfnc_argv 


RXFNC_FI ELDS 1 

dd ? 

dw ? 

dd ? 

dw ? 

dw ? 

dd ? 


rxfnc retc; dd ? 

RXFNCCAL_PARM ends 


;* same size as an unsigned. 
;* Pointer to function name. 
;* Length of function name. 
;* Current queue name. 

;* Length of queue name. 

;* Number of args in list. 

;* Pointer to argument list. 
;* List mimics argv list in 
;* REXXSAA - array of 
;* RXSTRINGs. 

;* Return value. 


Remarks 

Upon entry to RXFNCCAL, the name of the function to be invoked is defined by rxfncjiame and 
rxfnc_namel. The arguments to the function are indicated by rxfnc jargc and rxfnc_argv. If the named 
routine is invoked by a CALL instruction (rather than as a function call), the flag rxffsub is set “on.” 

On return from the exit, values in rxfnc Jlags indicate the status of the processing of the function. If 
neither rxfferr or rxffnfnd is “on,” the routine has been successfully invoked and has run successfully. 
The error flags are checked only if the exit returns 0. 

The flag rxffnfnd indicates that the exit could not locate the routine with the given name. The interpreter 
will give error 43, "Routine not found.” The flag rxfferr indicates that the parameters supplied to the 
routine were invalid. The interpreter will give error 40, "Invalid call to routine.” 

Note: The variable pool interface is fully enabled during calls to the RXFNC exits. Use the RXSHV_EXIT 
function to return the value of the function named in rxfncjiame, or return the value through the 
rxfnc_retc field of the exit parameter list. This routine may only be called once for each invocation 
of the exit to return a value. If the routine was invoked as a function and a result was not returned, 
the interpreter will give error 44, “Function did not return data.” If the routine was invoked as a 
subroutine, the returned result is optional. 
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RXCMD - 

Process Host Commands 


This service supports one subfunction, RXCMDHST. The request code for this subfunction is specified by 
the second parameter. 

RXCMDHST — Process host commands 

When called 

When interpretation is about to pass a command string to some external environment. 

Default action 

Pass the command to the external environment 

Action 

Pass the command to the external environment, if possible. 

Continuation 

If indicated by the results, raise the ERROR or FAILURE condition. Resume interpretation. 


C Language 

/*** Subfunction RXCMDHST -- Process Host Commands */ 


typedef struct { 
struct { 

unsigned rxfcfail : 1; 
unsigned rxfcerr : 1; 


} rxcmd_flags; 

PUCHAR 

USHORT 

PUCHAR 

USHORT 

RXSTRING 

RXSTRING 

} RXCMDHST_PARM; 


rxcmd_address ; 
rxcmd_addressl ; 
rxcmd_dl 1 ; 
rxcmdjill J en; 

rxcmd_command; 

rxcmd_retc; 


/* Condition flags */ 
/* Command failed. Trap with */ 
/* CALL or SIGNAL on FAILURE. */ 
/* Command ERROR occurred. */ 
/* Trap with CALL or SIGNAL on */ 
/* ERROR. */ 

/* Pointer to address name. */ 
/* Length of address name. */ 
/* dll name for command. */ 
/* Length of dll name. 0 *»> */ 
/* .EXE file. */ 
I* The command string. */ 
/* Pointer to return code */ 
I* buffer. User allocated. */ 
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RXCMD - 

Process Host Commands 


Assembler Language 

;*** Subfunction RXCMDHST — Process Host Commands 


rxfcfail db ? 

rxfcerr db ? 


* Command failed. Trap with 

* CALL or SIGNAL on FAILURE. 

* Command ERROR occurred. 

* Trap with CALL or SIGNAL on 

* ERROR. 


RXCMD_FIELD$ RECORD rxfcfail : 1, rxfcerr: 1, pad: 14 


RXCMDHST_PARM struc 


rxcmd_f 1 ags 

RXCMD FIELDS 1 

rxcmd_address 

dd 

? 

rxcmd_addressl 

dw 

? 

rxcmd jil 1 

dd 

? 

rxcmd_dll_len 

dw 


rxcmd_ccmmand 

dd 

? 

rxcmd_retc 

dd 

? 

RXCMDHST PARM ends 




;* Condition flags 
;* Pointer to address name. 

;* Length of address name. 

;* dll name for command. 

;* Length of dll name. 0==.EXE 
;* The command string. 

;* Pointer to return code 
;* buffer. User allocated. 


Remarks 

On entry to the exit, rxcmd_retc defines a buffer that may be used to return a value to be used for the 
return code in character format (that is, numeric return codes must be formatted as a character string). 
The return code may be a non-numeric value. The parameter rxcmdjcommand contains the command 
string itself. The parameters rxcmdjdH and rxcmd_dlljen define the name of the dynalink library speci- 
fied in the ADDRESS instruction. 

The flags rxfcfail and rxfcerr are used by this exit to indicate that an ERROR or FAILURE condition has 
occurred. The exit controls the definition of what constitutes an ERROR or FAILURE of a command. 

Note: The variable pool interface and all subcommand-registration functions are fuily enabled during 
calls to the RXCMD exits. 
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RXMSQ - 
Manipulate Queue 


This service supports four subfunctions: RXMSQPLL, RXMSQPSH, RXMSQSIZ, and RXMSQNAM. The 
second parameter specifies the subfunction request code. The parameter list depends on the particular 
subfunction invoked. 


RXMSQPLL — Pull a line from the queue 

When called 

Used to interpret PULL. 

Default action 

Pull from the current default queue. 

Action 

Provide a result. 

Continuation 

Resume interpretation, using the result. 


C Language 

/*** Subfunction RXMSQPLL - Pull 

typedef struct { 

RXSTRING rxmsqjretc; 

} RXMSQPLL_PARM; 

Assembler Language 

;*** Subfunction RXMSQPLL - Pull 

RXMSQPLL_PARM struc 
rxrasq_retc dd ? 

RXMSQPLL_PARM ends 


Entry from Queue */ 

/* Pointer to dequeued entry */ 
/* buffer. User allocated. */ 

Entry from Queue 

;* Pointer to dequeued entry 
;* buffer. User allocated. 


Remarks 

This exit is invoked by the PULL and PARSE PULL instructions. Upon entry to RXMSQPLL, rxmsq_retc 
defines a buffer that may be used to return a value to be used for the line removed from the queue. 

RXMSQPSH — Place a line on the queue 

When called 

Used to interpret PUSH and QUEUE. 

Default action 

Push the value on the current default queue. 

Action 

Push the value on some queue where RXMSQPLL subsequently can fetch It. 

Continuation 

Resume interpretation. 
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RXMSQ - 
Manipulate Queue 


C Language 

/*** Subfunction RXMSQPSH — Push Entry on Queue */ 


typedef struct { 

struct { /* Operation flag */ 

unsigned rxfmlifo : 1; /* Stack entry LIFO if set, */ 

/* FIFO if reset. */ 

} rxmsq_flags; 

RXSTRING rxmsq value; /* The entry to be pushed. */ 

} RXMSQPSH_PARM; 


Assembler Language 

;*** Subfunction RXMSQPSH — Push Entry on Queue 
* 

; rxfmlifo db ? * Stack entry LIFO if set, 

; * FIFO if reset. 

RXMSQ_FIELDS RECORD rxfml ifo: l,pad: 15 

RXMSQPSH_PARM struc 

rxmsq_flags RXM$G_FIELDS 1 ; Operation flag 

rxmsq^value; dd ? ; The entry to be pushed. 

RXMSQPSH_PARM ends 


Remarks 

The line to be placed on the queue (rxmsq_vafue) is the result of evaluating the expression specified on a 
PUSH or QUEUE instruction, it Is the responsibility of the exit to handle truncation of this string if the exit 
has a restriction on the maximum width of the queue. The stacking order is indicated by the flag rxfmlifo. 

RXMSQSIZ — Return the number of lines in the queue 

When called 

Used to interpret the built-in function QUEUED. 

Default action 

Find the size of the current default queue. 

Action 

Return the size of the queue which RXMSQPLL pulls from. 

Continuation 

Use the returned value as the value of QUEUED. Resume interpretation. 

C Language 

/*** Subfunction RXMSQSIZ — Return the Current Queue Size */ 
typedef struct { 

ULONG rxmsq_size; /* Number of Lines in Queue */ 

} RXMSQSIZ_PARM; 
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RXMSQ - 
Manipulate Queue 


Assembler Language 

;*** Subfunction RXMSQSIZ — Return the Current Queue Size 


RXMSQSIZ_PARM struc 

rxmsq_size dd ? ;* Number of Lines in Queue 

RXMSQSIZ_PARM ends 


Remarks 

This exit is invoked by the QUEUED function and by the PULL and PARSE PULL instructions. 
On return, rxmsqjsize contains the number of lines in the data queue as an integer. 


RXMSQNAM — Set the name of the active queue 

Used to interpret Rxqueue( ,, SET‘\ newqueuename) operating system specific routine. 

Default action 

Change the current default queue to newname . 

Action 

Change the queue to be operated upon by RXMSQPLL, RXMSQPSH, and RXMSQSIZ. 

Continuation 

Resume interpretation. 


C Language 

/*** Subfunction RXMXQNAM — Set Current Queue Name */ 

typedef struct { 

PSZ rxmsq_name; /* Selector containing ASCI IZ */ 

/* queue name. Change length */ 
/* with DosReallocSeg if */ 

/* required. */ 

} RXMSQNAM_PARM; 

Assembler Language 

;*** Subfunction RXMXQNAM — Set Current Queue Name 


RXMSQNAM_PARM struc 

rxmsq_name dw ? ;* Selector containing ASCI IZ 

;* queue name. Change length 
;* with DosReallocSeg if 
;* required. 

RXMSQNAM_PARM ends 


Remarks 

This exit is invoked by the function RXQUEUEf^E^^ev/qt/euename). 
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RXSIO - 
Session I/O 


This service supports four subfunctions: RXSIOSAY, RXSIOTRC, RXSIOTRD, and RXSIODTR. The second 
parameter specifies the subfunction request code. The parameter list depends on the particular subfunc- 
tion invoked. 

RXSIOSAY — Output result of SAY to standard output stream 

When called 

To output the result of a SAY instruction. 

Default action 

Write to the session standard output device. 

Action 

Send the line. 

Continuation 

Resume interpretation. 

C Language 

/*** Subfunction RXSIOSAY — Perform SAY Clause */ 
typedef struct { 

RXSTRING rxsio_string; /* String to display. */ 

} RXSIOSAY_PARM; 


Assembler Language 

;*** Subfunction RXSIOSAY — Perform SAY Clause 
RXSIOSAY_PARM struc 

rxsio string dd ? ;* String to display. 

RXSIOSAY_PARM ends 


Remarks 

The line to be delivered to the standard output device is the result of evaluating the expression specified 
on a SAY instruction. This string may be any length up to the size of the standard output device (as deter- 
mined by default system processing). It Is the responsibility of the exit to handle truncation of this string 
If the string longer that the standard output device. 

RXSIOTRC — TRACE output processing/call to output TRACE results 

When called 

To output the result of each line of tracing. 

Default action 

Write to the session standard error device. 

Action 

Send the line. 

Continuation 

Resume interpretation. 
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RXSIO - 
Session I/O 


C Language 

/*** Subfunction RXSIOTRC — Write Trace Output */ 
typedef struct { 

RXSTRING rxsio_string; /* Trace line to display. */ 

} RXSIOTRC_PARM; 

Assembler Language 

;*** Subfunction RXSIOTRC — Write Trace Output 


RXSIOTRC_PARM struc 

rxsio string dd ? ;* Trace line to display. 

RXSIOTRC.PARM ends 


Remarks 

The line to be displayed at the standard error-output device is the result of a traced line. The form of the 
string contained in rxsiojstring is: 

Characters 1 though 6: the line number (with leading spaces). 

A space, followed by the traced program line, ended by a semicolon. 

RXSIOTRD — Read from STDIN stream 

When called 

To read the standard input stream (STDIN). Note that if the 'PULL 1 was satisfied by something from 
the queue, this routine is not called. 

Default action 

Read from the default character input stream. 

Action 

Read a line. 

Continuation 

Resume interpretation 

C Language 

/*** Subfunction RXSIOTRD — Read Input from the Terminal */ 
typedef struct { 

RXSTRING rxsiotrd_retc; /* RXSTRING for output. Note: */ 

/* user allocates output */ 

/* buffer with DosAllocSegO */ 

/* or DosAllocHuge(). */ 

} RXSIOTRD_PARM; 

Assembler Language 

;*** Subfunction RXSIOTRD — Read Input from the Terminal 


RXSIOTRD_PARM struc 

rxsiotrdjretc dd ? ;* RXSTRING for output. Note: 

;* user allocates output 
;* buffer with DosAllocSegO 
;* or DosAllocHuge(). 

RXSIOTRD_PARM ends 
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RXSIO - 
Session I/O 

Remarks 

This exit is invoked by the instructions PULL and PARSE PULL when the active data queue is empty. (The 
PARSE LINEIN instruction does not invoke this exit) 

Upon entry, rxsio_retc defines a RXSTRING that may be used to return a value to be used for the line read 
from STDIN. REXX initializes this field to be a RXSTRING having a 250-character buffer. If additional 
length is needed, the system exit must allocate the output buffer with DosAllocSeg or DosAllocHuge. 

RXSIODTR — Debug read 

When called 

To read from the session character stream when for interactive debug. This routine differs from 
RXSIOTRD because it is not dependent on the state of the queue. 

Default action 

Read from the default character input stream. 

Action 

Read a line. 

Continuation 

Resume interpretation 

C Language 

Debug read from STDIN: stream. 

/*** Subfunction RXSIODTR -- Read Debug Input from the Terminal */ 
typedef struct { 

RXSTRING rxsiotrdjretc; /* RXSTRING for output. Note: */ 

/* user allocates output */ 

/* buffer with DosAllocSegO */ 

/* or DosAllocHugeQ . */ 

} RXSIODTR_PARM; 

Assembler Language 

;*** Subfunction RXSIODTR — Read Debug Input from the Terminal 
RXSIODTR_PARM struc 

rxsiodtrjretc dd ? ;* RXSTRING for output. Note: 

;* user allocates output 
;* buffer with DosAllocSegO 
;* or DosAllocHugeQ • 

RXSIODTR_PARM ends 


Remarks 

This exit is invoked by STDIN input during interactive debugging (invoked by the TRACE instruction). 

Upon entry, rxsiojetc defines a RXSTRING that may be used to return a value to be used for the line read 
from the STDIN stream. REXX initializes this field to a RXSTRING having a 250-character buffer. If addi- 
tional length is needed, the system exit must allocate the output buffer with DosAllocSeg or 
DosAllocHuge. 
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RXHLT - 
Halt Processing 


This service supports two subfunctions: RXHLTCLR and RXHLTTST. The second parameter specifies the 
request code for each subfunction. The parameter list depends on the particular subfunction invoked. 

RXHLTCLR — Clear halt indicator 

This exit subfunction has no inputs or outputs. It is invoked by the interpreter to reset the external flag 
after RXHLTTST has returned a flag value of 1. 

When called 

After raising HALT and before the next (potential) call of RXHLTTST. 

Default action 

The interpreter makes use of the system facilities for resetting the polling of external interrupts. 

Action 

Reset the polling of the external interrupt. 

Continuation 

Continue interpretation 

RXHLTTST - Test halt indicator 

When called 

RXHLTTST is called by the interpreter to poll whether an external attempt has been made to interrupt 
the execution. The interpreter must make enough calls to ensure that any execution that could be 
halted by this mechanism is eventually halted. 

Default action 

The interpreter makes use of the system facilities for polling external interrupts. 

Action 

Set the result to indicate whether the external interrupt has occurred. 

Continuation 

Raise the HALT condition if the interrupt has occurred. Continue interpretation. 

C Language 

/*** Subfunction RXHSTTST — Test for HALT Condition */ 
typedef struct { 

struct { /* Halt flag */ 

unsigned rxfhhalt : 1; /* Set if HALT occurred. */ 

} rxhlt_flags; 

} RXHLTTST_PARM; 

Assembler Language 

;*** Subfunction RXHSTTST — Test for HALT Condition 


; rxfhhalt db ? * Set if HALT occurred. 

RXHLTJIELDS RECORD rxfhhalt : l.pad: 15 


RXHLTTST PARM struc 

rxhlt flags RXHLT FIELDS 1 ;* Halt flag 

RXHLTTST PARM ends 
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RXHLT - 
Halt Processing 


Remarks 

This exit informs the REXX interpreter when a HALT condition has been raised. It is invoked at the end of 
each clause. Upon return, the rxfhhalt flag will Indicate whether a HALT condition has occurred (1 = Halt, 
0 = No Halt). RXHLTTST may also return a string that is available through the built-in function 
CONDITION(D). This string is returned by using the SHVEXIT function of the RXVAR routine. This routine 
may only be called once for each invocation of the exit to return a value. 
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RXTRC - 

Test External Trace Indicator 


This service supports one subfunction: RXTRCTST. The request code for the subfunction is specified by 
the second parameter. 

RXTRCTST — Test external trace indicator 

When called 

The tracing feature of REXX can be controlled externally to the program. RXTRC is called by the 
interpreter to poll whether the external indication says that trace is active. 

Default action 

The interpreter makes use of the system facilities for indicating this condition. 

Action 

Set the result to indicate whether the external condition is set. 

Continuation 

Continue with or without tracing, according to the result. 

C Language 

/*** Subfunction RXTRCTST — Test for TRACE Condition */ 

struct rxtrc_parm { 
struct { 

unsigned rxf trace : 1; /* External trace setting */ 

} rxtrc_flags; 

} 

Assembler Language 

;*** Subfunction RXTRCTST — Test for TRACE Condition 


; rxf trace db ? * Set to run external trace. 

RXTRC_FIELDS RECORD rxftrace:l,pad:15 

RXTRCTST PARM struc 

rxtrcjflags RXTRC_FIELDS 1 ;* Trace flags 

RXTRCTST_PARM ends 


Remarks 

This exit is invoked at the end of each clause. Upon return from this exit, rxftrace will indicate whether 
an external trace condition has occurred (1 = External Trace, 0 = No External Trace). 

Note: If the rxftrace flag Is set from 0 to 1, on return, REXX will begin interactive debug mode. When the 
rxftrace flag is set from 1 to 0, trace will turn off interactive debug mode. 
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RXINI - 

Initialization Processing 


This service supports one subfunction, RXINIEXT. The second parameter specifies the request code for 
the subfunction. 


RXINIEXT — Initialization processing 

This exit has no inputs or outputs. It is called before the first instruction of the program is interpreted. 
Note: The variable pooi interface is enabled when this exit is called. 

When called 

After the last instruction of the subject program is interpreted. 

Default action 

Nothing. 

Action 

This is an opportunity for the system to adapt to the change of context; for example, to initialize so 
that the other user exits will work. 

Continuation 

Resume interpretation 
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RXTER - 

Termination Processing 


This service supports one subfunction, RXTEREXT. The second parameter specifies the request code for 
this subfunction. 

RXTEREXT — Termination processing 

This exit has no inputs or outputs. It is called after the last instruction of the program is interpreted. If 
the termination exit fails (that is, returns -1), no action is taken. 

Note: The variable pool interface is enabled when this exit is called. 

When called 

After the last instruction of the subject program is interpreted. 

Default action 

Do nothing. 

Action 

This is an opportunity for the system to adapt to the change of context. 

Continuation 

Resume, leaving the interpreter. 


Asynchronous Request Interface 

Using the system exits for signaling halt and trace conditions causes a noticeable loss in performance. 
This loss is caused by the interpreter calling the exit routines for every REXX instruction. However, on 
most calls no action is taken by the exit routines. 

The asynchronous request interface provides a similar capability to the system exits for halt and trace 
conditions without causing a loss of performance. The following three APIs allow an application to 
directly signal REXX for a trace or halt event. 
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RxHaltSet - 
Inform Halt Condition 


This call allows the user to inform the REXX interpreter that a halt condition has occurred. 


RxHaltSet (Processld, Threadld) 


Parameters 

Processld (P/D) - input 

A pointer to the process ID that the REXX interpreter is running under. This is the same process as 
the program that issued the call to the REXXSAA DLL routine. 

Threadld (TID) — input 

The thread ID that the REXX interpreter is running under. This is the same thread as the program 
that issued the call to the REXXSAA DLL routine. 

Returns 

0 RXARIJDK 

1 RXARI_NOT_FOUND 

2 RXARI_PROCESSING_ERROR 

Remarks 

This call will not be processed if the target REXX program is executing with the RXHLT exit enabled. 
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RxTraceSet - 
Turn On Debug Mode 


This call allows the user to inform the REXX interpreter that the interpreter should turn on the interactive 
debug mode. 


RxTraceSet (Processld, Threadld) 


Parameters 

Processld (P/D) - input 

A pointer to the process ID that the REXX interpreter is running under. This is the same process as 
the program that issued the call to the REXXSAA DLL routine. 

Threadld ( TID ) - input 

The thread ID that the REXX interpreter is running under. This is the same thread as the program 
that issued the call to the REXXSAA DLL routine. 

Returns 

0 RXARI_OK 

1 RXARI_NOT_FOUND 

2 RXARI_PROCESSING_ERROR 

Remarks 

This call will not be processed if the target REXX program is executing with the RXTRC exit enabled. 
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RxTraceReset - 

Turn Off Interactive Debug Mode 


This call allows the user to inform the REXX interpreter that the Interpreter should turn off the interactive 
debug mode. 


RxTraceReset (Processld, Threadld) 


Parameters 

Processld (P/D) - input 

A pointer to the process ID that the REXX interpreter is running under. This is the same process as 
the program that issued the call to the REXXSAA DLL routine. 

Threadld ( TID ) — input 

The thread ID that the REXX interpreter is running under. This is the same thread as the program 
that issued the call to the REXXSAA DLL routine. 

Returns 

0 RXARI_OK 

1 RXARI_NOT_FOUND 

2 RXARI_PROCESSINGJERROR 

Remarks 

This call will not be processed if the target REXX program is executing with the RXTRC exit enabled. 
Tracing is only turned off if the trace was originally turned on by a call to RxTraceSet. 
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Appendix. Errors Returned from REXX Calls 

Numeric Order 


Number Name Explanation 


0x01 

RXSUBCOMJSREG 

The subcommand environment has been regis- 
tered. 

0x01 

RXSUBCOM_ERROR 

An error in execution has occurred; the interpreter 
raises an ERROR condition. 

0x02 

RXSUBCOM_FAILURE 

A failure in execution has occurred; the interpreter 
raises a FAILURE condition. 

1002 

RXSUBCOMJMOEMEM 

There is insufficient memory available to complete 
this request. 

1003 

RXSUBCOM_BADTYPE 

Incorrect registration type; an internal failure may 
have occurred. Retry the operation; if this error 
persists, contact your IBM representative. 

0 

RXSUBCOM_OK 

The subcommand has been executed successfully. 

0 

RXFUNC_OK 

The call to the API completed successfully. 

0 

RXMACRO_OK 

The call to the API completed successfully. 

1 

RXMACRO_NO_STORAGE 

There was not enough memory to complete the 
requested function. 

2 

RXMACRO_NOT_FOUND 

The requested function was not found in the 
macrospace. 

3 

RXMACRO_EXTENSION_REQUIRED 

An extension is required for the file name passed 
to the function. 

4 

RXMACRO_ALREADY_EXISTS 

Duplicate functions cannot be loaded from the 
requested file. 

5 

RXMACRO_FILE_ERROR 

An error occurred accessing the requested file. 

6 

RXMACRO_SIGNATURE_ERROR 

The file specified as containing macrospace func- 
tion images is not valid. 

7 

RXMACRO_SOURCE_NOT_FOUND 

The requested file was not found. 

8 

RXMACROJNVALID_POSITION 

An invalid search-order position request flag was 
passed to the function. 

10 

RXSUBCOM_DUP 

A duplicate environment name has been regis- 
tered successfully; there is either: 



• An .EXE environment by the same name reg- 
istered in another process; or 

• A DLL environment by the same name regis- 
tered in another DLL; to address this subcom- 
mand, its library name must be specified. 

10 

RXFUNCDEFINED 

The requested function is already defined in the 
table. 

20 

RXSUBCOM_MAXREG 

Cannot register anymore blocks. 

20 

RXFUNC.NOMEM 

There is not enough memory to add a new function 
to the table. 
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Number Name Explanation 


30 RXSUBCOM_NOTREG 


This indicates either: 



* Registration was unsuccessful due to dupli- 
cate environment and dynalink names 
(RxSubcom Register); or 

• The subroutine environment is not registered 
(other RxSubcom functions). 

30 RXFUNC_NOTREG 


The requested function is not registered in the 
table. 

40 RXSUBCOM_NOCANDROP 


The subroutine has been registered as “not 
droppable.” 

40 RXFUNC_MODNOTFND 


The dynamic link library module could not be 
found. 

50 RXSUBCOM_LOADERR 


An error has occurred while loading a routine into 
memory; most commonly this is due to a missing 
file. 

50 RXFUNC.ENTNOTFND 


The function entry point could not be found. 

127 RXSUBCOM_NOPROC 


The RxSubcom routine was not found; check for a 
missing file. 

Alphabetic Order 



Name 

Number 

Explanation 

RXFUNC_DEFINED 

10 

The requested function is already defined in the 
table. 

RXFUNC_ENTNOTFND 

50 

The function entry point could not be found. 

RXFUNC_NOMEM 

20 

There is not enough memory to add a new function 
to the table. 

RXFUNC.NOTREG 

30 

The requested function is not registered in the 
table. 

RXFUNC_MODNOTFND 

40 

The dynamic link library module could not be 
found. 

RXFUNC_OK 

0 

The call to the API completed successfully. 

RXMACRO_ALREADY_EXISTS 

4 

Duplicate functions cannot be loaded from the 
requested file. 

RXMACRO_EXTENSION_REQUIRED 

3 

An extension is required for the file name passed 
to the function. 

RXMACRO_FILE_ERROR 

5 

An error occurred accessing the requested file. 

RXMACRO_INVALID_POSITION 

8 

An invalid search-order position request flag was 
passed to the function. 

RXMACRO_NO_STORAGE 

1 

There was not enough memory to complete the 
requested function. 

RXMACRO_NOT_FOUND 

2 

The requested function was not found in the 
macrospace. 

RXMACRO_OK 

0 

The call to the API completed successfully. 

RXMACRO_SIGNATURE_ERROR 

6 

The file specified as containing macrospace func- 
tion images is not valid. 

RXMACRO_SOURCEJMOT_FOUND 

7 

The requested file was not found. 

RXSUBCOMJSREG 

0x01 

The subcommand environment has been regis- 


tered. 
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Name 

Number 

Explanation 

RXSUBCOMJERROR 

0x01 

An error in execution has occurred; the interpreter 
raises an ERROR condition. 

RXSUBCOM_FAILURE 

0x02 

A failure in execution has occurred; the interpreter 
raises a FAILURE condition. 

RXSUBCOM_NOEMEM 

1002 

There is insufficient memory available to complete 
this request. 

RXSUBCOM_BADTYPE 

1003 

Incorrect registration type; an internal failure may 
have occurred. Retry the operation; if this error 
persists, contact your IBM representative. 

RXSUBCOM_OK 

0 

The subcommand has been executed successfully. 

RXSUBCOM_DUP 

10 

A duplicate environment name has been regis- 
tered successfully; there is either: 



• An .EXE environment by the same name reg- 
istered in another process, or 

• A DLL environment by the same name regis- 
tered in another DLL; to address this subcom- 
mand, its library name must be specified. 

RXSUBCOM_MAXREG 

20 

Cannot register anymore blocks. 

RXSUBCOM_NOTREG 

30 

This indicates either: 



• Registration was unsuccessful due to dupli- 
cate environment and dynalink names 
(RxSubcom Register); or 

• The subroutine environment is not registered 
(other RxSubcom functions). 

RXSUBCOM_NOCANDROP 

40 

The subroutine has been registered as “not 
droppable.” 

RXSUBCOM_LOADERR 

50 

An error has occurred while loading a routine into 
memory; most commonly this is due to a missing 
file. 

RXSUBCOM.NOPROC 

127 

The RxSubcom routine was not found; check for a 
missing file. 
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